API errors

If an API request results in an error, the Ripple Payments Direct API returns a response with an HTTP error code in the 400 or 500 series. The error response body also contains more information about the error and recommended next steps when available.

Error response body schema

An error response from the Ripple Payments Direct API has the following response body schema:

Array of objects

Error response body.

Array
code
string [ 1 .. 140 ] characters

Unique error code that identifies this error.

title
string

Gives a brief summary of the error.

type
string

Specifies the type of error. These are the supported error types.

Enum: Description
AUTH_ERROR

[User Error]
Invalid or expired expired auth token.

NOT_FOUND

[User Error]
Unable to find the requested resource.

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

Describes the error in greater detail and contains error recovery instructions and next steps when available.

timestamp
string <date-time>

Indicates the time at which the error occurred.

Error handling

You can determine how to handle an error by using the type value.
Use the type to determine next steps
Use the value of the type field rather than the code or description fields to determine the error recovery action you need to take. This is because new error code values may be added, and the description associated with an error, may be improved as part of routine enhancements.

User errors

If the error type is AUTH_ERROR, NOT_FOUND, or USER_ERROR, the cause may be such things as an expired auth token, a malformed request URL, or a request body that has invalid values.The description field in the error response body for these types of errors typically includes more details about the error and actionable information when available.

System errors

Errors with the CONFIGURATION_ERROR and SYSTEM_ERROR type are internal or server errors.

These errors cannot be overcome without Ripple's help. Contact Ripple technical support for help and provide the error information you received in the response. This includes the error code, title, error type, description, timestamp, and the API endpoint that returned the error.

Example error

This JSON snippet shows an example 404 error when looking up an invalid quote ID.

Copy
Copied!
{
  "status": 404,
  "errors": [
    {
      "code": "USR_011",
      "title": "Invalid quote collection",
      "type": "USER_ERROR",
      "description": "Unable to find quote collection with ID: {0}. Try again with a valid quote collection ID.",
      "timestamp": "2023-11-02T18:26:00.000123Z"
    }
  ],
  "timestamp": "2023-11-02T18:26:00.000Z"
}