Erreurs

Wajub utilise les codes de statut HTTP conventionnels : 2xx signifie que la requête a réussi, 4xx que le problème vient de votre requête, 5xx qu'il vient de chez nous. Chaque erreur porte la même enveloppe qu'un succès, plus un objet errors lorsqu'un champ est en cause.

Codes de statut

Forme d'une erreur

status est toujours le libellé HTTP, jamais la chaîne littérale error. message est une phrase destinée à vos logs, pas à un switch.

Le message du 404 nomme la ressource : Payment Not Found, Customer Not Found, Transfer Not Found, Invoice Not Found, Link Not Found, Beneficiary Not Found, Account Not Found, et Resource Not Found pour tout le reste.

Erreurs de validation

Un 422 ajoute un objet errors qui associe chaque champ rejeté à sa liste de messages. Les champs imbriqués utilisent la notation pointée, qui reprend le chemin dans le corps de votre requête.

Deux échecs qui ne relèvent pas de la validation arrivent aussi en 422 sur le champ idempotency_key : un en-tête Idempotency-Key mal formé, et une clé réutilisée avec un payload différent. Voir Idempotence.

Chaque réponse a un identifiant de requête

X-Request-Id est défini sur chaque réponse, erreurs comprises. Journalisez-le à côté de votre propre identifiant de corrélation, et indiquez-le quand vous ouvrez un ticket au support. Vous pouvez aussi envoyer votre propre valeur, jusqu'à 64 caractères : elle vous est renvoyée au lieu d'être générée.

curl https://api.wajub.com/payments/trx_01JXXXXXXXXXXXXX \
-H "Authorization: $WAJUB_API_KEY" \
-H "X-Request-Id: order-4172-attempt-1"

Aiguiller votre code après un échec

Aiguillez sur le code de statut, jamais sur message. Trois familles méritent un traitement différent : un 422 est un bug dans votre payload et une nouvelle tentative n'y changera rien ; un 429 est un problème de rythme et la réponse vous indique combien de temps attendre ; un 5xx ou un 502 est transitoire et justifie un nombre limité de nouvelles tentatives.

const res = await fetch(url, { method: 'POST', headers, body });

if (res.status === 422) {
const { errors } = await res.json();
return showFieldErrors(errors);
}

if (res.status === 429) {
const wait = Number(res.headers.get('retry-after') ?? 1);
return retryAfter(wait * 1000);
}

if (!res.ok) {
throw new Error(`Wajub ${res.status} ${res.headers.get('x-request-id')}`);
}

Le SDK PHP transforme chaque code de statut en exception dédiée : un bloc catch suffit donc à séparer les trois familles.

Chacune expose errorCode, httpStatus, errors et raw, le corps de la réponse décodé.