API errors
This page lists all error codes returned by Payments Direct 2.0.
Each entry includes:
- Code
- Type
- Title
- Description
- HTTP status
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.
Complete set of API error codes
Below is the complete set of API error codes available in Payments Direct 2.0.
| Code | Type | Title | Description | Status |
|---|---|---|---|---|
| USR_001 | USER_ERROR | Bad request | Invalid request. Check your request parameters and try again. | 400 |
| USR_002 | NOT_FOUND | Resource not found | The requested resource could not be found. | 404 |
| USR_003 | USER_ERROR | User error | Unable to process request due to a user error. | 400 |
| USR_011 | USER_ERROR | Invalid quote | Unable to find quote with the specified ID. Try again with a valid quote. | 404 |
| USR_012 | USER_ERROR | Invalid quote collection | Unable to find a quote collection with the specified ID. Try again with a valid quote collection ID. | 404 |
| USR_013 | USER_ERROR | Insufficient quote amount | Unable to create a quote because the quote amount is not sufficient to cover transaction fees. Try again with a larger quote amount. | 400 |
| USR_014 | USER_ERROR | Incorrect pay in category | Unable to create quote because the pay in category you specified is not one of the supported values. Try again with a supported pay in category value. | 400 |
| USR_015 | USER_ERROR | Incorrect payout category | Unable to create quote because the payout category you specified is not one of the supported values. Try again with a supported payout category value. | 400 |
| USR_016 | USER_ERROR | Invalid country/currency pair | Unable to create a quote because the country and currency pair you provided is invalid. Try again with valid values. | 400 |
| USR_017 | USER_ERROR | Invalid request body | Unable to create quote because one or more required fields are missing from the request body. Try again with all required fields. One or more required fields are missing. | 400 |
| USR_018 | USER_ERROR | Invalid quote amount type | Unable to create quote due to invalid quote amount type. The value should be one of SOURCE_AMOUNT or DESTINATION_AMOUNT. | 400 |
| USR_019 | USER_ERROR | Invalid quote amount | The quote amount value must be between 1 and 100000000. Try again with a valid value. | 400 |
| USR_020 | USER_ERROR | Invalid country code | Unable to create quote due to invalid country code in the request body. The country code should be 2 characters long. | 400 |
| USR_021 | USER_ERROR | Invalid currency code | Unable to create quote due to invalid currency code in the request body. The currency code should be 3-5 characters long. | 400 |
| USR_022 | USER_ERROR | Invalid source and destination pair | Unable to create a quote because a payment using the specified source country, source currency, destination currency, and blockchain information is not supported. Try again with valid values. | 400 |
| USR_023 | USER_ERROR | Invalid destination currency/payout category pair | Unable to create a quote because the destination currency is not supported for the selected payout category. Try again with a supported destination currency for that payout category. | 400 |
| USR_051 | USER_ERROR | Invalid value. 36-character long UUID is expected | Unable to parse UUID value for the specified payment field. Try again with valid UUID value. | 400 |
| USR_052 | USER_ERROR | Missing quote ID | Missing value for quoteId field. Try again with valid input value. | 400 |
| USR_053 | USER_ERROR | Missing beneficiary identity ID | Missing value for beneficiaryIdentityId field. Try again with valid input value. | 400 |
| USR_054 | USER_ERROR | Field size constraint violation | The field does not meet the expected size requirements. Try again with valid input value. | 400 |
| USR_055 | USER_ERROR | Invalid request body | Unable to create payment because the request body is empty or contains unexpected characters. Try again with all valid request body. | 400 |
| USR_056 | USER_ERROR | Missing request body | Unable to create payment due to missing request body in JSON format. Try again with a request body. | 400 |
| USR_057 | USER_ERROR | Invalid quote ID | Unable to find a quote with the specified ID. Try again with a valid quote ID. | 400 |
| USR_058 | USER_ERROR | Quote expired | The quote with the specified ID is expired. Try again with a valid quote ID. | 400 |
| USR_059 | USER_ERROR | Invalid PII data | Unable to find the identity with the specified ID. Try again with valid identity ID. | 400 |
| USR_060 | USER_ERROR | Mismatched use case | Payment use case not supported for the specified identity. | 400 |
| USR_061 | USER_ERROR | Missing sourceOfCash or purposeCode | Missing sourceOfCash or purposeCode. | 400 |
| USR_068 | USER_ERROR | Field value constraint violation | The field value must be within the expected range. Try again with valid input value. | 400 |
| USR_069 | USER_ERROR | Not active PII data | The identity with the specified ID is not active. Try again with valid identity ID. | 400 |
| USR_070 | USER_ERROR | Mismatching PII type | The identity with the specified ID type is not matching expected type. Try again with valid identity ID. | 400 |
| USR_071 | USER_ERROR | Payment type is not allowed | The specified payment type created is not allowed. Please submit a payment with other payment types. | 400 |
| USR_072 | USER_ERROR | Too many labels | The request is trying to add too many labels. The maximum amount of labels for a payment is the specified value. | 400 |
| USR_073 | USER_ERROR | Mismatched blockchain network | The blockchain network associated with the payment's beneficiary doesn't match the blockchain network you specified in the quote. Try again with a valid blockchain network value. | 400 |
| USR_074 | USER_ERROR | Missing beneficiary's blockchain network | The beneficiary id's details is missing blockchain network. | 400 |
| USR_075 | USER_ERROR | Missing or unsupported content type | The request is either missing the 'Content-Type' header or the header contains an unsupported value. Set the 'Content-Type' header value to 'application/json' and try again. | 415 |
| USR_076 | USER_ERROR | Missing Request Field Error | A required field is missing. Provide the required field and try again. | 400 |
| USR_101 | USER_ERROR | Bad Request | Invalid request. Check your request body and try again. | 400 |
| USR_102 | USER_ERROR | Bad request | Unable to get identity. Identity ID should be in UUID format. | 400 |
| USR_103 | NOT_FOUND | Identity not found | No identity exists for the specified ID. | 404 |
| USR_104 | USER_ERROR | Invalid request | The identity has already been deactivated. | 422 |
| USR_105 | USER_ERROR | Too many requests | Too many requests. Please try again later. | 429 |
| USR_106 | USER_ERROR | Invalid account number | The account number is invalid. | 400 |
| USR_107 | USER_ERROR | Invalid request | Invalid request. Provide the "PstlAdr.AdrLine" value as an array and try again. | 400 |
| USR_108 | USER_ERROR | Invalid request | Invalid request. Provide the required field and try again. | 400 |
| USR_109 | USER_ERROR | Invalid request | Invalid request. The field's format is invalid. | 400 |
| USR_110 | USER_ERROR | Financial instrument already exists | One financial instrument already exists for the specified ID. | 409 |
| USR_111 | USER_ERROR | Invalid request | Field validation error for the specified value. | 400 |
| USR_151 | USER_ERROR | Invalid identity information | Payment failed due to one or more errors in the beneficiary identity details. Create a new beneficiary identity with valid values and try again. | 400 |
| USR_152 | USER_ERROR | Conflicting beneficiary name info | Payment failed because both Cdtr.Nm and Cdtr.StrdNm fields are populated in the beneficiary identity information. Only one of these fields must be present. If the beneficiary is an institution, specify only Cdtr.Nm. If the beneficiary is an individual, specify only Cdtr.StrdNm. | 400 |
| USR_164 | USER_ERROR | Invalid payment amount | The payment amount you specified is greater than the maximum allowed amount. Try again with a smaller payment amount. | 400 |
| USR_165 | USER_ERROR | Invalid payment amount | The payment amount you specified is less than the minimum allowed amount. Try again with a larger payment amount. | 400 |
| USR_166 | USER_ERROR | Incorrect account number | Payment failed because the account number you provided doesn’t match the beneficiary’s account number. | 400 |
| USR_167 | USER_ERROR | Invalid originator identity ID | Unable to find originator with the originatorIdentityId provided. Try again with a valid originator ID. | 400 |
| USR_168 | USER_ERROR | Invalid beneficiary identity ID | Unable to find beneficiary with the beneficiaryIdentityId provided. Try again with a valid beneficiary ID. | 400 |
| USR_169 | USER_ERROR | Unable to find payment destination | Payment failed because the beneficiary’s account you specified could not be found. Try again with valid beneficiary information. | 400 |
| USR_171 | USER_ERROR | Incorrect request data format | Payment failed because one or more fields in the request contain incorrectly formatted data. Try again with correctly formatted request parameters. | 400 |
| USR_172 | USER_ERROR | Inactive beneficiary account | Payment failed because the beneficiary account you specified for this payment is inactive. Try again with a valid and active beneficiary account. | 400 |
| USR_173 | USER_ERROR | Conflicting beneficiary name info | Payment failed because both Cdtr.Nm and Cdtr.StrdNm fields are populated in the beneficiary identity information. Only one of these fields must be present. If the beneficiary is an institution, specify only Cdtr.Nm. If the beneficiary is an individual, specify only Cdtr.StrdNm. | 400 |
| USR_201 | USER_ERROR | Transaction limit reached | Payment failed because you have reached the 24‑hour transaction limit. Try again later. | 400 |
| USR_202 | USER_ERROR | Transaction amount limit exceeded | The transaction amount you requested is greater than the allowed the allowed maximum per transaction. | 400 |
| USR_203 | USER_ERROR | Insufficient credit | Payment failed because the payment amount of in USD is higher than your available credit amount of in USD. If you recently paid an invoice, the available credit amount shown here may be subject to change. | 400 |
| USR_204 | USER_ERROR | Invoice past due | Payment failed because you have a past-due invoice. If you have already submitted a payment confirmation, try again later or contact technical support. | 400 |
| USR_205 | USER_ERROR | Insufficient balance | Payment failed due to insufficient balance. Add funds to your account and try again. | 400 |
| USR_206 | USER_ERROR | Too many pending direct debit transactions | Payment failed because you have too many pending direct debit transactions. Try again after some of the pending transactions are complete. | 400 |
| USR_251 | USER_ERROR | Request parameter missing | The request parameter %s is missing. Please provide the required parameter and try again. | 400 |
Payment Failures
Some errors occur after a payment has been created but before it completes. These are categorized as payment failures. Unlike request-time errors, failures may require operational follow-up, such as adding funds, resolving credit limits, or correcting beneficiary information.
Common causes:
- Insufficient balance
- Credit or transaction limits exceeded
- Past-due invoices
- Invalid or inactive beneficiary account details
How to handle payment failures:
-
Check the error
codein the payment’s failure reason. - Look up the code in the table above.
- Follow the description to correct the issue.
- Retry the payment only if the condition has been resolved.
Payment Failure Codes Reference
Here’s the filtered subset of error codes that represent payment failures:
| Code | Type | Title | Description | Status |
|---|---|---|---|---|
| USR_151 | USER_ERROR | Invalid identity information | Payment failed due to one or more errors in the beneficiary identity details. Create a new beneficiary identity with valid values and try again. | 400 |
| USR_152 | USER_ERROR | Conflicting beneficiary name info | Payment failed because both Cdtr.Nm and Cdtr.StrdNm fields are populated in the beneficiary identity information. Only one of these fields must be present. If the beneficiary is an institution, specify only Cdtr.Nm. If the beneficiary is an individual, specify only Cdtr.StrdNm. | 400 |
| USR_166 | USER_ERROR | Incorrect account number | Payment failed because the account number you provided doesn’t match the beneficiary’s account number. | 400 |
| USR_169 | USER_ERROR | Unable to find payment destination | Payment failed because the beneficiary’s account you specified could not be found. Try again with valid beneficiary information. | 400 |
| USR_171 | USER_ERROR | Incorrect request data format | Payment failed because one or more fields in the request contain incorrectly formatted data. Try again with correctly formatted request parameters. | 400 |
| USR_172 | USER_ERROR | Inactive beneficiary account | Payment failed because the beneficiary account you specified for this payment is inactive. Try again with a valid and active beneficiary account. | 400 |
| USR_173 | USER_ERROR | Conflicting beneficiary name info | Payment failed because both Cdtr.Nm and Cdtr.StrdNm fields are populated in the beneficiary identity information. Only one of these fields must be present. If the beneficiary is an institution, specify only Cdtr.Nm. If the beneficiary is an individual, specify only Cdtr.StrdNm. | 400 |
| USR_201 | USER_ERROR | Transaction limit reached | Payment failed because you have reached the 24‑hour transaction limit. Try again later. | 400 |
| USR_203 | USER_ERROR | Insufficient credit | Payment failed because the payment amount in USD is higher than your available credit amount in USD. If you recently paid an invoice, the available credit amount shown here may be subject to change. | 400 |
| USR_204 | USER_ERROR | Invoice past due | Payment failed because you have a past-due invoice. If you have already submitted a payment confirmation, try again later or contact technical support. | 400 |
| USR_205 | USER_ERROR | Insufficient balance | Payment failed due to insufficient balance. Add funds to your account and try again. | 400 |
| USR_206 | USER_ERROR | Too many pending direct debit transactions | Payment failed because you have too many pending direct debit transactions. Try again after some of the pending transactions are complete. | 400 |