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.

Un chemin qui encode une barre oblique ou une barre oblique inverse, %2F ou %5C en majuscules comme en minuscules, répond ce 404 quelle que soit la clé. Placez chaque identifiant tel quel dans le chemin ; la chaîne de requête n'est pas concernée.

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. Chaque 422 le porte : un refus qui ne concerne aucun champ précis range son message sous errors.request.

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.

Erreurs de restriction

Wajub peut restreindre un compte, par exemple après un contrôle de risque. Un appel refusé par une restriction répond 403 avec un error_code : aiguillez votre code sur error_code, et gardez message pour vos logs.

Un paiement refusé ainsi n'est pas débité et reste pending. Quand toute l'API est fermée, le 403 porte aussi un champ restriction avec le type de restriction. Un plafond de transaction atteint sur POST /payments/{id} (unitaire, journalier ou mensuel) n'est pas une restriction : il répond 402 avec error_code: limit_exceeded, comme merchant_not_verified pour un compte qui ne peut pas encore encaisser en live.

Blocages Shield

Un paiement bloqué par Shield répond 403 avec error_code: shield_blocked, et block_reference porte la référence à donner au support. Aucun prestataire n'a été contacté, rien n'a été débité, et le paiement reste pending.

Refus de payout

Un payout refusé avant d'exister répond 422 avec un error_code à côté de message et errors. Aiguillez votre code sur ce code. Les mêmes codes reviennent sur chaque ligne refusée de POST /transfers/batch, dans results[].error_code, et sur POST /accounts/{id}/payouts.

POST /transfers/batch ajoute les siens : idempotency_key_required (400, le lot n'a pas d'Idempotency-Key), reference_reused_in_batch (une ligne réutilise une référence de ce lot pour un autre payout), et processing_error ou payout_queue_busy sur une ligne qui n'a pas pu partir cette fois : ces deux-là peuvent être réessayées telles quelles. Un POST /transfers seul répond dans ce dernier cas 429 avec error_code: payout_queue_busy et Retry-After. POST /accounts/{id}/payouts ajoute account_not_lite, account_not_active, account_not_connected et payout_destination_missing (422), live_mode_only (400) et nothing_to_pay_out (409).

Une requête mal formée, par exemple un champ manquant, répond le 422 habituel sans error_code : l'objet errors nomme le champ.

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_CSUGajfv9xh0XQ5wu2lx \
-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é.