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:

Array of objects

Array of objects. Each object contains the following fields:

Array

code

string [ 1 .. 140 ] characters

Unique error code that identifies this error.

title

string

A brief summary of the error.

type

string

The type of error. Supported values are:

Enum:	Description
AUTH_ERROR	[User Error] Invalid or expired authentication token.
NOT_FOUND	[User Error] The requested resource could not be found.
USER_ERROR	[User Error] Incorrect or malformed request.
CONFIGURATION_ERROR	[System Error] Internal configuration error. Contact Ripple technical support.
SYSTEM_ERROR	[System Error] Internal server error. Contact Ripple technical support.

description

string

Concise explanation of the error. May include recovery instructions.

status

integer

Associated HTTP status code.

timestamp

string <date-time>

Time at which the error occurred.

Example Error Response

Copy

Copied!

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