Errors#
Yusr uses conventional HTTP status codes and returns a JSON error object with a stable, machine-readable
code. Branch on code, not on message: messages are written for people and can be more specific than the
default text (for example No such transaction: txn_nope instead of the generic not-found message).
The error object#
Every non-2xx response from the API has the same shape:
| Field | Type | Description |
|---|---|---|
code | string | Stable error code from the catalogue below. |
message | string | Human-readable explanation. Safe to log; do not parse it. |
param | string, optional | The request field or header at fault, such as amount, reference or Idempotency-Key. |
request_id | string | Unique ID of this request. It is also sent in the X-Request-Id response header. |
Some errors carry extra top-level fields. A duplicate_reference error includes the transaction that already uses
the reference, so you can carry on with it instead of creating another one:
The transaction field is shortened here; the API returns the full transaction object.
HTTP status codes#
| Status | Meaning |
|---|---|
200 OK, 201 Created | The request succeeded. 201 means an object was created. |
400 Bad Request | The request is malformed or a parameter is invalid. See param. |
401 Unauthorized | The API key is missing, invalid, expired after a roll, or revoked. |
403 Forbidden | The key is valid but not allowed to do this: live mode not enabled, sandbox-only endpoint, IP not on the allowlist, or account suspended. |
404 Not Found | The object does not exist in this mode. Test objects are invisible to live keys and vice versa. |
409 Conflict | Duplicate reference, idempotency key reuse, or the object's state does not allow the action. |
422 Unprocessable Entity | The request is well formed but breaks an account rule, such as the amount range or a volume cap. |
429 Too Many Requests | You hit a rate limit. Wait for Retry-After seconds. |
500, 502, 503 | Something went wrong on our side. Retry with backoff and the same Idempotency-Key. |
Error catalogue#
Every error the REST API returns uses one of these codes. Each row has its own link anchor, for example
#duplicate_reference.
| Code | HTTP | Meaning and fix |
|---|---|---|
| invalid_request | 400 | The request is invalid. Fix: Check the |
| authentication_failed | 401 | Invalid or missing API key. Fix: Send |
| permission_denied | 403 | You do not have permission to perform this action. Fix: Your team role does not allow this action. Ask an Owner or Admin. |
| sandbox_only | 403 | This endpoint is only available with test keys. Fix: Use a test secret key ( |
| merchant_not_live | 403 | Live mode is not enabled for this account. Complete verification to go live. Fix: Submit your business verification in the dashboard. Live keys work after approval. |
| merchant_suspended | 403 | This account is suspended. Contact support. Fix: Contact support. Your account has been suspended by the compliance team. |
| ip_not_allowed | 403 | Requests from this IP address are not allowed for this key. Fix: Add your server IP to the key allowlist in the dashboard, or remove the allowlist. |
| not_found | 404 | The requested resource was not found. Fix: Check the ID. Test-mode objects are not visible with live keys and vice versa. |
| duplicate_reference | 409 | A transaction with this reference already exists. Fix: References must be unique per account and mode. The existing transaction is returned in the |
| idempotency_conflict | 409 | This Idempotency-Key was already used with a different request body. Fix: Use a new Idempotency-Key for a request with a different body. |
| idempotency_in_progress | 409 | A request with this Idempotency-Key is still being processed. Fix: Wait for the first request with this key to finish, then retry. |
| invalid_state | 409 | The resource is not in a state that allows this action. Fix: The transaction or object is not in a state that allows this action. |
| amount_out_of_range | 422 | The amount is outside the allowed range for this account. Fix: Send an amount (in kobo) within the minimum and maximum set for your account. |
| limit_exceeded | 422 | This request exceeds a volume limit on your account. Fix: Your daily or monthly volume cap was reached. Contact support to raise your limits. |
| rate_limited | 429 | Too many requests. Retry after the time in the Retry-After header. Fix: Slow down and retry after the number of seconds in the |
| processing_error | 502 | The payment could not be processed. Please try again. Fix: Retry the request with the same Idempotency-Key. If it persists, contact support. |
| service_unavailable | 503 | The service is temporarily unavailable. Please retry shortly. Fix: Retry with exponential backoff and the same Idempotency-Key. |
| internal_error | 500 | An unexpected error occurred. Fix: Retry the request. If it persists, contact support with the |
Dashboard sign-in codes#
These codes come only from signing in to the dashboard and related account flows (email verification, password reset, two-factor codes). The REST API never returns them.
| Code | HTTP | Meaning and fix |
|---|---|---|
| email_not_verified | 403 | Verify your email address before signing in. Fix: Click the link in the verification email, or request a new one. |
| account_locked | 423 | Too many failed sign-in attempts. Try again in 15 minutes. Fix: Wait 15 minutes or reset your password. |
| invalid_credentials | 401 | Incorrect email or password. Fix: Check your email and password. |
| invalid_code | 401 | The verification code is invalid or expired. Fix: Enter the current 6-digit code from your authenticator app, or a recovery code. |
| invalid_token | 400 | This link is invalid or has expired. Fix: Request a new link. |
| csrf_failed | 403 | Your session token is missing or invalid. Refresh the page and try again. Fix: Refresh the page to get a new session token. |
Retrying safely#
A payment must never be created twice, so retry only when it is safe. Send an Idempotency-Key with every POST
that creates something and reuse the same key and byte-identical body on each retry. Within 24 hours,
Yusr returns the original response (with the header Idempotent-Replayed: true) instead of repeating the
action. Responses with status 429 or 5xx are not stored, so a retry with the same key runs again.
| Situation | Safe to retry? | How |
|---|---|---|
| Network error or timeout, no response | Yes | Same Idempotency-Key and body. |
429 rate_limited | Yes | Wait the number of seconds in Retry-After, then retry. |
409 idempotency_in_progress | Yes | The first request is still running. Wait Retry-After (1 second), then retry. |
500 internal_error, 502 processing_error, 503 service_unavailable | Yes | Exponential backoff with jitter, same Idempotency-Key. |
400, 401, 403, 404, 422 | No | Fix the request, key or account setting first. Retrying unchanged gets the same error. |
409 duplicate_reference | No | Use the transaction in the error body, or choose a new reference. |
409 idempotency_conflict | No | You reused a key with a different body. Use a new key for a new request. |
409 invalid_state | No | Retrieve the object and act on its current status. |
The official SDKs do this for you: they send an idempotency key on every create, reuse it across automatic retries,
and retry network errors, 408, 429 and 5xx responses with exponential backoff.
Handling errors in code#
This example creates a transaction and handles the two errors you are most likely to meet while integrating:
duplicate_reference (carry on with the existing transaction) and invalid_request (report the bad field).
SDK error classes#
Both SDKs turn error responses into typed exceptions that carry the code, HTTP status, param and request ID.
Node.js#
| Class | When | Typical code |
|---|---|---|
AuthenticationError | 401 | authentication_failed |
PermissionError | 403 | permission_denied, merchant_not_live, sandbox_only, ip_not_allowed |
InvalidRequestError | 400, 422 | invalid_request, amount_out_of_range, limit_exceeded |
NotFoundError | 404 | not_found |
ConflictError | 409 | duplicate_reference (see .transaction), idempotency_conflict, invalid_state |
RateLimitError | 429 | rate_limited (see .retryAfter, in seconds) |
APIError | 5xx or unreadable response | service_unavailable, processing_error, internal_error |
ConnectionError | No response (DNS, TLS, reset, timeout) | connection_error, timeout |
SignatureVerificationError | Webhook signature check failed | signature_verification_failed |
WaitTimeoutError | waitForPayment reached timeoutMs | wait_timeout |
Every class extends YusrError, which carries code, status, param, requestId and raw (the decoded
error body).
PHP#
| Exception | When | Typical code |
|---|---|---|
AuthenticationException | 401 | authentication_failed |
PermissionException | 403 | permission_denied, merchant_not_live, sandbox_only, ip_not_allowed |
InvalidRequestException | 400, 422 | invalid_request, amount_out_of_range, limit_exceeded |
NotFoundException | 404 | not_found |
ConflictException | 409 | duplicate_reference (getTransaction()), idempotency_conflict, invalid_state |
RateLimitException | 429 | rate_limited (getRetryAfter(), in seconds) |
ApiException | 5xx or unreadable response | service_unavailable, processing_error, internal_error |
ConnectionException | No response | connection_error, timeout |
SignatureVerificationException | Webhook signature check failed | signature_verification_failed |
All exceptions extend Yusr\Exception\YusrException and expose getErrorCode(), getHttpStatus(),
getParam(), getRequestId() and getRaw().