# API errors overview

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.

## Error response body schema

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. |


## Example error response


```json
{
  "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"
}
```

## 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 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](/products/payments-direct-2/api-docs/error-codes/api-errors) reference.

For guidance on retry strategy, exponential backoff, and monitoring, see [Error handling and retry strategy](/products/payments-direct-2/api-docs/best-practices/error-handling).