{"templateId":"markdown","versions":[{"version":"v2026.03","label":"v2026.03","link":"/products/payments-direct-2/api-docs/error-codes/payments-direct-api-errors","default":true,"active":true,"folderId":"eb16255d"},{"version":"v2025.11","label":"v2025.11","link":"/products/payments-direct-2/v2025.11/api-docs/error-codes/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":[]},"type":"markdown"},"seo":{"title":"API errors overview","description":"User guides, API reference, and support resources.","siteUrl":"https://docs.ripple.com/products/custody","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"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":["Ripple Payments Direct 2.0 returns standardized error responses for all API requests."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Errors are consistent across services, making it easier to log, monitor, and troubleshoot integration issues."]},{"$$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":["All error responses share the same structure:"]},{"$$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":["status"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The HTTP status code associated with the error."]}]},{"$$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":"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  \"code\": \"USR_067\",\n  \"type\": \"USER_ERROR\",\n  \"title\": \"Insufficient balance\",\n  \"description\": \"Payment failed due to insufficient balance. Add funds before retrying.\",\n  \"status\": 402,\n  \"timestamp\": \"2025-08-21T10:15:30Z\"\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."]}]},{"$$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":["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":"a","attributes":{"href":"/products/payments-direct-2/api-docs/error-codes/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":"a","attributes":{"href":"/products/payments-direct-2/api-docs/best-practices/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-03-31T03:43:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/payments-direct-2/api-docs/error-codes/payments-direct-api-errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}