Skip to content
YusrDocs

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:

JSON
{
  "error": {
    "code": "invalid_request",
    "message": "expires_in must be at least 600 seconds (10 minutes)",
    "param": "expires_in",
    "request_id": "req_01M47EGDW0JXS8PXZVTH0SC419"
  }
}
FieldTypeDescription
codestringStable error code from the catalogue below.
messagestringHuman-readable explanation. Safe to log; do not parse it.
paramstring, optionalThe request field or header at fault, such as amount, reference or Idempotency-Key.
request_idstringUnique 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:

JSON
{
  "error": {
    "code": "duplicate_reference",
    "message": "A transaction with this reference already exists.",
    "param": "reference",
    "request_id": "req_01M47EGDJG6NSRHZ2DRGH1H8ZT"
  },
  "transaction": {
    "id": "txn_01M47EG1XHH9S3MTQD3FJ156FT",
    "object": "transaction",
    "mode": "test",
    "status": "pending",
    "amount": 2500000,
    "reference": "order-1042"
  }
}

The transaction field is shortened here; the API returns the full transaction object.

HTTP status codes#

StatusMeaning
200 OK, 201 CreatedThe request succeeded. 201 means an object was created.
400 Bad RequestThe request is malformed or a parameter is invalid. See param.
401 UnauthorizedThe API key is missing, invalid, expired after a roll, or revoked.
403 ForbiddenThe 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 FoundThe object does not exist in this mode. Test objects are invisible to live keys and vice versa.
409 ConflictDuplicate reference, idempotency key reuse, or the object's state does not allow the action.
422 Unprocessable EntityThe request is well formed but breaks an account rule, such as the amount range or a volume cap.
429 Too Many RequestsYou hit a rate limit. Wait for Retry-After seconds.
500, 502, 503Something 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.

API error codes
CodeHTTPMeaning and fix
invalid_request400

The request is invalid.

Fix: Check the param field for the invalid parameter and the message for details.

authentication_failed401

Invalid or missing API key.

Fix: Send Authorization: Bearer sk_test_... (or sk_live_...). Make sure the key has not been rolled or revoked.

permission_denied403

You do not have permission to perform this action.

Fix: Your team role does not allow this action. Ask an Owner or Admin.

sandbox_only403

This endpoint is only available with test keys.

Fix: Use a test secret key (sk_test_) to call sandbox endpoints.

merchant_not_live403

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_suspended403

This account is suspended. Contact support.

Fix: Contact support. Your account has been suspended by the compliance team.

ip_not_allowed403

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_found404

The requested resource was not found.

Fix: Check the ID. Test-mode objects are not visible with live keys and vice versa.

duplicate_reference409

A transaction with this reference already exists.

Fix: References must be unique per account and mode. The existing transaction is returned in the transaction field.

idempotency_conflict409

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_progress409

A request with this Idempotency-Key is still being processed.

Fix: Wait for the first request with this key to finish, then retry.

invalid_state409

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_range422

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_exceeded422

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_limited429

Too many requests. Retry after the time in the Retry-After header.

Fix: Slow down and retry after the number of seconds in the Retry-After header.

processing_error502

The payment could not be processed. Please try again.

Fix: Retry the request with the same Idempotency-Key. If it persists, contact support.

service_unavailable503

The service is temporarily unavailable. Please retry shortly.

Fix: Retry with exponential backoff and the same Idempotency-Key.

internal_error500

An unexpected error occurred.

Fix: Retry the request. If it persists, contact support with the request_id.

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.

Dashboard sign-in error codes
CodeHTTPMeaning and fix
email_not_verified403

Verify your email address before signing in.

Fix: Click the link in the verification email, or request a new one.

account_locked423

Too many failed sign-in attempts. Try again in 15 minutes.

Fix: Wait 15 minutes or reset your password.

invalid_credentials401

Incorrect email or password.

Fix: Check your email and password.

invalid_code401

The verification code is invalid or expired.

Fix: Enter the current 6-digit code from your authenticator app, or a recovery code.

invalid_token400

This link is invalid or has expired.

Fix: Request a new link.

csrf_failed403

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.

SituationSafe to retry?How
Network error or timeout, no responseYesSame Idempotency-Key and body.
429 rate_limitedYesWait the number of seconds in Retry-After, then retry.
409 idempotency_in_progressYesThe first request is still running. Wait Retry-After (1 second), then retry.
500 internal_error, 502 processing_error, 503 service_unavailableYesExponential backoff with jitter, same Idempotency-Key.
400, 401, 403, 404, 422NoFix the request, key or account setting first. Retrying unchanged gets the same error.
409 duplicate_referenceNoUse the transaction in the error body, or choose a new reference.
409 idempotency_conflictNoYou reused a key with a different body. Use a new key for a new request.
409 invalid_stateNoRetrieve 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).

# -i prints the status line and headers (including X-Request-Id) before the JSON body.
curl -i https://api.yusr.ng/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: checkout-order-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500000,
    "reference": "order-1042",
    "customer": { "name": "Ada Obi", "email": "ada@example.com" }
  }'

# Reusing the reference with a different Idempotency-Key returns:
# HTTP/1.1 409 Conflict
# { "error": { "code": "duplicate_reference", ... }, "transaction": { ... } }

SDK error classes#

Both SDKs turn error responses into typed exceptions that carry the code, HTTP status, param and request ID.

Node.js#

ClassWhenTypical code
AuthenticationError401authentication_failed
PermissionError403permission_denied, merchant_not_live, sandbox_only, ip_not_allowed
InvalidRequestError400, 422invalid_request, amount_out_of_range, limit_exceeded
NotFoundError404not_found
ConflictError409duplicate_reference (see .transaction), idempotency_conflict, invalid_state
RateLimitError429rate_limited (see .retryAfter, in seconds)
APIError5xx or unreadable responseservice_unavailable, processing_error, internal_error
ConnectionErrorNo response (DNS, TLS, reset, timeout)connection_error, timeout
SignatureVerificationErrorWebhook signature check failedsignature_verification_failed
WaitTimeoutErrorwaitForPayment reached timeoutMswait_timeout

Every class extends YusrError, which carries code, status, param, requestId and raw (the decoded error body).

PHP#

ExceptionWhenTypical code
AuthenticationException401authentication_failed
PermissionException403permission_denied, merchant_not_live, sandbox_only, ip_not_allowed
InvalidRequestException400, 422invalid_request, amount_out_of_range, limit_exceeded
NotFoundException404not_found
ConflictException409duplicate_reference (getTransaction()), idempotency_conflict, invalid_state
RateLimitException429rate_limited (getRetryAfter(), in seconds)
ApiException5xx or unreadable responseservice_unavailable, processing_error, internal_error
ConnectionExceptionNo responseconnection_error, timeout
SignatureVerificationExceptionWebhook signature check failedsignature_verification_failed

All exceptions extend Yusr\Exception\YusrException and expose getErrorCode(), getHttpStatus(), getParam(), getRequestId() and getRaw().