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
errorCodefor programmatic decisions. Do not compare free-text messages.Validation can return HTTP
400or422.INVALID_REQUEST_DATAidentifies structured validation failures; the message gives safe field guidance. Do not assumeerrorsis 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.
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