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.
Apart from the OAuth token endpoints, every error response shares the same structure:
The HTTP status code for the response. Appears once, at the top level of the response body.
One or more error objects describing what went wrong. A single request can fail for more than one reason, so always iterate this array even when it contains a single entry. Each object contains the following fields:
Unique error code that identifies this error.
A brief summary of the error.
The type of error. Supported values are:
| Enum Value | Description |
|---|---|
| AUTH_ERROR | <b>[User Error]</b></br>Invalid or expired authentication token. |
| NOT_FOUND | <b>[User Error]</b></br>The requested resource could not be found. |
| USER_ERROR | <b>[User Error]</b></br>Incorrect or malformed request. |
| CONFIGURATION_ERROR | <b>[System Error]</b></br>Internal configuration error.</br>Contact Ripple technical support. |
| SYSTEM_ERROR | <b>[System Error]</b></br>Internal server error.</br>Contact Ripple technical support. |
Concise explanation of the error. May include recovery instructions.
Time at which the error occurred.
Every error response has a top-level status and an errors array containing one or more error objects. status appears once, at the top level, and is not a field of the individual error objects. Always iterate errors as an array, even when it contains a single entry.
{
"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"
}
]
}When building your integration:
- Always log and monitor code and status.
- Check the error code first when deciding how to handle errors.
- Treat description as guidance for humans, not programmatic logic.
- Use status for general categorization, not for recovery logic.
For the complete list of error codes and troubleshooting steps, see the API Error Codes reference.
This is the initial release of Payments Direct error handling. The schema and error codes are stable for integration, but descriptions will be expanded with more actionable troubleshooting guidance in future updates.