Ripple Payments Direct 2.0 returns standardized error responses for all API requests.
Errors are consistent across services, making it easier to log, monitor, and troubleshoot integration issues.
All error responses share the same structure:
| Field | Type | Description |
|---|---|---|
code | string | A unique identifier for the error (for example, USR_067). |
type | string | The error category. One of: AUTH_ERROR, USER_ERROR, NOT_FOUND, CONFIGURATION_ERROR, SYSTEM_ERROR. |
title | string | A short, human-readable summary of the error. |
description | string | A concise explanation of the error. May include recovery instructions. |
status | integer | The HTTP status code associated with the error. |
timestamp | string (ISO 8601) | The time at which the error occurred. |
{
"code": "USR_067",
"type": "USER_ERROR",
"title": "Insufficient balance",
"description": "Payment failed due to insufficient balance. Add funds before retrying.",
"status": 402,
"timestamp": "2025-08-21T10:15:30Z"
}When building your integration:
- Always log and monitor the
codeandstatusfields 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
descriptionfield as guidance for humans, not programmatic logic. Its wording may change between releases.
Some errors are transient and can be retried; others indicate a condition that must be resolved before resubmitting.
| Error type | HTTP status | Retry? | Recommended action |
|---|---|---|---|
USER_ERROR | 400, 404, 415 | No | Fix the request and resubmit. |
USER_ERROR | 402 | No (until resolved) | Resolve the underlying condition (balance, limits, or identity details) before retrying. |
NOT_FOUND | 404 | No | Verify the resource ID and resubmit. |
AUTH_ERROR | 401 | After token refresh | Regenerate your access token and retry. |
AUTH_ERROR | 403 | No | Verify that your token has the required scopes for this action. |
SYSTEM_ERROR | 500 | Yes, with backoff | Retry with exponential backoff. Contact Ripple technical support if the issue persists. |
CONFIGURATION_ERROR | 500 | No | Contact 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.