Errors

Wajub uses conventional HTTP status codes: 2xx succeeded, 4xx is something about your request, 5xx is something about ours. Every error carries the same envelope as a success, plus an errors object when a field is at fault.

Status codes

Error shape

status is always the HTTP reason phrase, never the literal string error. message is one sentence meant for your logs, not for a switch.

The 404 message names the resource: Payment Not Found, Customer Not Found, Transfer Not Found, Invoice Not Found, Link Not Found, Beneficiary Not Found, Account Not Found, and Resource Not Found for anything else.

Validation errors

A 422 adds an errors object mapping each rejected field to its list of messages. Nested fields use dot notation, matching the path in your request body. Every 422 carries it: a refusal that concerns no single field puts its message under errors.request.

Two non-validation failures also arrive as a 422 on the idempotency_key field: a malformed Idempotency-Key header, and a key reused with a different payload. See Idempotency.

Restriction errors

Wajub can restrict an account, for example after a risk review. A call that a restriction refuses answers 403 with an error_code: branch on error_code, and keep message for your logs.

A payment refused this way is not charged and stays pending. When the whole API is closed, the 403 also carries a restriction field with the restriction type. A transaction limit reached on POST /payments/{id} (single, daily or monthly) is not a restriction: it answers 402 with error_code: limit_exceeded, as does merchant_not_verified for an account that cannot take live payments yet.

Shield blocks

A payment Shield blocks answers 403 with error_code: shield_blocked, and block_reference carries the reference to quote to support. No provider was contacted, nothing was charged, and the payment stays pending.

Payout refusals

A payout refused before it exists answers 422 with an error_code next to message and errors. Branch on the code. The same codes come back on each refused line of POST /transfers/batch, in results[].error_code, and on POST /accounts/{id}/payouts.

POST /transfers/batch adds three of its own: idempotency_key_required (400, the batch has no Idempotency-Key), reference_reused_in_batch (a line reuses a reference of this batch for a different payout), processing_error on a line that failed on our side, and payout_queue_busy on a line that waited too long behind another live payout of the account: those two are safe to retry as is. A single POST /transfers in that last case answers 429 with error_code: payout_queue_busy and Retry-After. POST /accounts/{id}/payouts adds account_not_lite, account_not_active, account_not_connected and payout_destination_missing (422), live_mode_only (400) and nothing_to_pay_out (409).

A request that is malformed, such as a missing field, answers the usual 422 without an error_code: the errors object names the field.

Every response has a request ID

X-Request-Id is set on every response, including errors. Log it next to your own correlation ID, and quote it when you open a support ticket. You can also send your own value, up to 64 characters, and it is echoed back instead of being generated.

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

Branching on a failure

Branch on the status code, never on message. Three families deserve different treatment: a 422 is a bug in your payload and retrying will not help, a 429 is a timing problem and the response tells you how long to wait, a 5xx or 502 is transient and worth a bounded retry.

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')}`);
}

The PHP SDK turns each status code into a dedicated exception, so a catch block is enough to separate the three families:

Every one of them exposes errorCode, httpStatus, errors and raw, the decoded response body.