Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Errors and Safe Retries

Interpret On/Off Ramp responses, handle payment errors and reconcile transaction status before retrying requests.

Read API success separately from payment success

{
  "success": true,
  "message": "Query successful",
  "data": {}
}

data varies by endpoint: it can be an object, array, scalar, or be absent when there is no payload. List endpoints do not all use the same pagination shape. Read the endpoint's response section.

HTTP 200 or 201 with success: true means the request was accepted or read successfully. A payment may still be pending. Verify its transaction status and match the saved reference, amount and currency before fulfilling an order.

Handle errors

API errors use success: false, message, and statusCode. Depending on the failure, they also include errorCode, attemptId, errors, path, method, and a human-readable timestamp. Fields may be absent; infrastructure errors can return non-JSON bodies.

  • Use a recognized errorCode for programmatic decisions. Do not compare free-text messages.

  • Validation can return HTTP 400 or 422. INVALID_REQUEST_DATA identifies structured validation failures; the message gives safe field guidance. Do not assume errors is always an array of {field, message} objects.

  • Save your reference, the attempt ID, HTTP status and error code for support. Do not log secret keys, authorization links or full customer payloads.

  • Treat timestamps in error responses as display text, not an ISO timestamp contract.

Retry without creating a second payment

A unique reference helps identify an operation. It does not promise that every duplicate POST returns the original response. Some routes reject duplicates. Only use an Idempotency-Key header where the endpoint explicitly documents it.

Situation
What to do

400 / 422 invalid input

Fix the indicated fields before retrying

401 / 403

Check credential type, environment, account access and any IP restrictions

404

Check the identifier, business and environment

409

Read the existing operation; do not generate a new reference automatically

429

Back off and respect Retry-After if supplied

Timeout, lost connection or 5xx after a payment POST

Treat the outcome as unknown. Check the saved reference before another initiation

Failed read-only GET

Retry with bounded exponential backoff and jitter

If the API returns recovery instructions such as retrySafe, follow that endpoint's recovery contract. A missing field is not permission to retry a money-moving request. A failed payout can still have a reservation pending reconciliation; do not assume funds are immediately available for another payout.

Practical server-side response handling

See the error-code reference and payment status endpoints.

Last updated