# 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:


```json
{
  "$ref": "#/components/schemas/directerror",
  "components": {
    "schemas": {
      "directerror": {
        "schema": "http://json-schema.org/draft-06/schema#",
        "id": "file://po11#",
        "description": "Payments Direct API error schema",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "Errors": {
            "type": "array",
            "description": "Array of objects. Each object contains the following fields:",
            "items": {
              "properties": {
                "code": {
                  "type": "string",
                  "description": "Unique error code that identifies this error.",
                  "minLength": 1,
                  "maxLength": 140,
                  "examples": [
                    "USR_067"
                  ]
                },
                "title": {
                  "type": "string",
                  "description": "A brief summary of the error."
                },
                "type": {
                  "type": "string",
                  "description": "The type of error. Supported values are:",
                  "enum": [
                    "AUTH_ERROR",
                    "CONFIGURATION_ERROR",
                    "SYSTEM_ERROR",
                    "NOT_FOUND",
                    "USER_ERROR"
                  ],
                  "x-enumDescriptions": {
                    "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."
                  }
                },
                "description": {
                  "type": "string",
                  "description": "Concise explanation of the error. May include recovery instructions."
                },
                "status": {
                  "type": "integer",
                  "description": "Associated HTTP status code."
                },
                "timestamp": {
                  "type": "string",
                  "format": "date-time",
                  "description": "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** 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](/products/payments-direct-2/v2025.11/api-docs/error-codes/api-errors) reference.

Note
This is the initial release of Payments Direct 2.0 error handling.
The schema and error codes are stable for integration, but descriptions will be expanded with more actionable troubleshooting guidance in future updates.