Skip to content

Payments Direct returns standardized error responses across its API operations, making it easier to log, monitor, and troubleshoot integration issues.

The OAuth token endpoints are the exception. They follow the OAuth 2.0 error format instead, described in Authentication errors.

Error response body schema

Apart from the OAuth token endpoints, every error response shares the same structure: a top-level status, and an errors array containing one or more error objects.

FieldTypeDescription
statusintegerThe HTTP status code for the response.
errorsarrayOne or more error objects describing what went wrong. A single request can fail for more than one reason.

Each object in the errors array contains the following fields:

FieldTypeDescription
codestringA unique identifier for the error (for example, USR_067).
typestringThe error category. One of: AUTH_ERROR, USER_ERROR, NOT_FOUND, CONFIGURATION_ERROR, SYSTEM_ERROR.
titlestringA short, human-readable summary of the error.
descriptionstringA concise explanation of the error. May include recovery instructions.
timestampstring (ISO 8601)The time at which the error occurred.
Where to read the HTTP status

status appears once, at the top level of the response. It is not a field of the individual error objects. Always iterate errors as an array, even when it contains a single entry.

Example error response

{
  "status": 402,
  "errors": [
    {
      "code": "USR_067",
      "type": "USER_ERROR",
      "title": "Insufficient balance",
      "description": "Payment failed due to insufficient balance. Add funds to your account and try again.",
      "timestamp": "2025-08-21T10:15:30Z"
    }
  ]
}

Handling API errors

When building your integration:

  • Always log and monitor the code and status fields in every error response.
  • Check the error code first when deciding how to handle errors. Do not rely solely on the HTTP status code.
  • Treat the description field as guidance for humans, not programmatic logic. Its wording may change between releases.

Transient vs. permanent errors

Some errors are transient and can be retried; others indicate a condition that must be resolved before resubmitting.

Error typeHTTP statusRetry?Recommended action
USER_ERROR400, 404, 415NoFix the request and resubmit.
USER_ERROR402No (until resolved)Resolve the underlying condition (balance, limits, or identity details) before retrying.
NOT_FOUND404NoVerify the resource ID and resubmit.
AUTH_ERROR401After token refreshRegenerate your access token and retry.
AUTH_ERROR403NoVerify that your token has the required scopes for this action. On payment operations, a 403 can also mean the payment exists but belongs to a different tenant.
SYSTEM_ERROR500Yes, with backoffRetry with exponential backoff. Contact Ripple technical support if the issue persists.
CONFIGURATION_ERROR500NoContact Ripple technical support.

For the complete list of error codes, see the API error codes reference.

For guidance on retry strategy, exponential backoff, and monitoring, see Error handling and retry strategy.

API errors

Payments Direct API