{"templateId":"markdown","versions":[{"version":"v2026.04","label":"v2026.04","link":"/products/payments-direct-2/api-docs/error-handling/payments-direct-api-errors","default":true,"active":false,"folderId":"eb16255d"},{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/v2026.03/api-docs/error-handling/payments-direct-api-errors","default":false,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/error-handling/payments-direct-api-errors","default":false,"active":false,"folderId":"eb16255d"}],"sharedDataIds":{"sidebar":"sidebar-products/payments-direct-2/@v2025.11/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"API errors overview","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"api-errors-overview","__idx":0},"children":["API errors overview"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Payments Direct"," returns standardized error responses across its API operations, making it easier to log, monitor, and troubleshoot integration issues."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The OAuth token endpoints are the exception. They follow the OAuth 2.0 error format instead, described in ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/payments-direct-2/v2026.03/api-docs/get-started/authentication#authentication-errors"},"children":["Authentication errors"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-response-body-schema","__idx":1},"children":["Error response body schema"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Apart from the OAuth token endpoints, every error response shares the same structure: a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", and an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array containing one or more error objects."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The HTTP status code for the response."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["array"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more error objects describing what went wrong. A single request can fail for more than one reason."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each object in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," array contains the following fields:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A unique identifier for the error (for example, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USR_067"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The error category. One of: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["title"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A short, human-readable summary of the error."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A concise explanation of the error. May include recovery instructions."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string (ISO 8601)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The time at which the error occurred."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Where to read the HTTP status"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," appears once, at the top level of the response. It is not a field of the individual error objects. Always iterate ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["errors"]}," as an array, even when it contains a single entry."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"example-error-response","__idx":2},"children":["Example error response"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"status\": 402,\n  \"errors\": [\n    {\n      \"code\": \"USR_067\",\n      \"type\": \"USER_ERROR\",\n      \"title\": \"Insufficient balance\",\n      \"description\": \"Payment failed due to insufficient balance. Add funds to your account and try again.\",\n      \"timestamp\": \"2025-08-21T10:15:30Z\"\n    }\n  ]\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"handling-api-errors","__idx":3},"children":["Handling API errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When building your integration:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Always ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["log and monitor"]}," the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," fields in every error response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Check the error code first"]}," when deciding how to handle errors. Do not rely solely on the HTTP status code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Treat the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}," field as guidance for humans, not programmatic logic. Its wording may change between releases."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"transient-vs-permanent-errors","__idx":4},"children":["Transient vs. permanent errors"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Some errors are transient and can be retried; others indicate a condition that must be resolved before resubmitting."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Error type"},"children":["Error type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Retry?"},"children":["Retry?"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Recommended action"},"children":["Recommended action"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400, 404, 415"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Fix the request and resubmit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["USER_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["402"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No (until resolved)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Resolve the underlying condition (balance, limits, or identity details) before retrying."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify the resource ID and resubmit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["After token refresh"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Regenerate your access token and retry."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify that your token has the required scopes for this action. On payment operations, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["403"]}," can also mean the payment exists but belongs to a different tenant."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, with backoff"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Retry with exponential backoff. Contact Ripple technical support if the issue persists."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Yes, after the stated time"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A maintenance window is in force. The error description states when service is expected to resume. Retry after that time rather than immediately."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CONFIGURATION_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Ripple technical support."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the complete list of error codes, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/payments-direct-2/v2026.03/api-docs/error-handling/api-errors"},"children":["API error codes"]}," reference."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For guidance on retry strategy, exponential backoff, and monitoring, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/payments-direct-2/v2026.03/api-docs/error-handling"},"children":["Error handling and retry strategy"]},"."]}]},"headings":[{"value":"API errors overview","id":"api-errors-overview","depth":1},{"value":"Error response body schema","id":"error-response-body-schema","depth":2},{"value":"Example error response","id":"example-error-response","depth":2},{"value":"Handling API errors","id":"handling-api-errors","depth":2},{"value":"Transient vs. permanent errors","id":"transient-vs-permanent-errors","depth":3}],"frontmatter":{"seo":{"title":"API errors overview"}},"lastModified":"2026-10-15T04:38:19.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/v2026.03/api-docs/error-handling/payments-direct-api-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}