> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Error response format and the full list of Ramps API error codes.

When a request to the Ramps API fails, the response carries a five-digit application `code`, the error `type`, a `detail` and the HTTP `status`:

```json theme={null}
{
  "code": 20039,
  "type": "TermsAndConditionsNotAcceptedException",
  "detail": {
    "message": "Customer '3fa85f64-5717-4562-b3fc-2c963f66afa6' has not accepted the current Terms and Conditions."
  },
  "status": 400
}
```

* **Branch on `code`**, not on the message: messages may change, codes do not.
* **`detail`** is usually an object with a `message`. Field validation errors (`20000`) return an object keyed by field name instead, each with a list of `{ message, code }`.
* **The HTTP status does not follow the code range.** A `200XX` code can come with `400`, `403`, `404` or `409`, and some `400XX` codes come with `400`. Read the status from the response, as listed below.
* A few codes are shared by more than one error — `40003` and `40004` in particular. Use `type` to tell them apart.

Each endpoint page lists the errors it can return, with examples. This page is the complete catalog.

## General

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20000` | 400 | `ValidationError` | One or more request fields are missing or invalid. `detail` lists the errors per field. | Fix the fields listed in `detail` and retry. |
| `20001` | 400 | `ParseError` | The request body could not be parsed (malformed JSON or multipart). | Check the body's syntax and `Content-Type`. |
| `40001` | 401 | `NotAuthenticated` | The access token is missing, invalid or expired. | [Acquire a new access token](https://docs.ripio.com/ramps-api/authentication/acquire-access-token.md). |
| `40003` | 403 | `PermissionDenied` | The token is not allowed to use this endpoint, or the feature is not enabled for your account (for example QR payments). | Check `type` and `detail`; contact Ripio to enable the feature. |
| `40004` | 404 | `NotFound` | The resource does not exist or is not visible to your account. A deactivated customer is also answered with `404` on `/customers/{id}/…` actions. | Check the identifier. |
| `40005` | 405 | `MethodNotAllowed` | The HTTP method is not supported on this endpoint. | Check the endpoint's reference page. |
| `40015` | 415 | `UnsupportedMediaType` | The `Content-Type` is not supported by this endpoint. | Send `application/json` (or `multipart/form-data` where the endpoint says so, as in support tickets). |
| `40029` | 429 | `Throttled` | Too many requests. | Retry after the number of seconds in `wait`. |
| `50003` | 503 | `ServiceUnavailable` | A downstream service is temporarily unavailable. | Retry later. If it persists, contact Ripio support. |

## Customers

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20014` | 400 | `EmailRequiredException` | The customer has no email, and this operation needs one. | Set it with [Update Customer](https://docs.ripio.com/ramps-api/customers/update-customer.md). |
| `20041` | 400 | `CustomerDeactivatedException` | The customer is deactivated and cannot operate. | See [Reactivate Customer](https://docs.ripio.com/ramps-api/customers/reactivate-customer.md). |
| `20063` | 409 | `CustomerHasPendingOperationsException` | The customer has operations in progress and cannot be deactivated yet. | Retry once they finish. |
| `20081` | 400 | `CustomerEmailFrozenException` | The email cannot change: the customer's KYC already verified it. | Contact Ripio support to change it. |
| `20098` | 400 | `KycServiceChangeEmailException` | The new email could not be applied to the customer's open identity verification. | Retry; if it persists, contact Ripio support. |
| `20106` | 409 | `CustomerAlreadyActiveException` | The customer is already active. | Nothing to do. |
| `20107` | 409 | `CustomerDeactivatedByRipioException` | The customer was deactivated by Ripio and cannot be reactivated by the partner. | Contact Ripio support. |

## Terms and Conditions and investor profile

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20039` | 400 | `TermsAndConditionsNotAcceptedException` | The customer has not accepted the active [Terms and Conditions](https://docs.ripio.com/ramps-api/terms-and-conditions/introduction.md). | Have them accept the current version and retry. |
| `20040` | 404 | `TermsAndConditionsNotFoundException` | No active Terms and Conditions match that `termsId` for the customer's country. | Fetch the current terms and send their `termsId`. |
| `20096` | 400 | `InvestorQuestionnaireVersionNotActiveException` | The questionnaire version answered is not the active one. | Fetch the [current questionnaire](https://docs.ripio.com/ramps-api/investor-profile/get-investor-questionnaire.md) and answer it again. |
| `20097` | 400 | `InvalidInvestorProfileAnswersException` | The questionnaire answers are incomplete or invalid. | Answer every question with one of its options. |
| `20099` | 400 | `InvestorProfileNotRequiredException` | The investor profile is not enabled for your account. | Skip this step. |
| `20100` | 400 | `InvestorProfileRequiredException` | Brazil: the customer has no valid investor profile. | Have them [submit it](https://docs.ripio.com/ramps-api/investor-profile/submit-investor-profile.md) and retry. |

## Identity verification (KYC)

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20003` | 400 | `UnsupportedCountryException` | The operation is not available for your account's country. | Contact Ripio. |
| `20004` | 400 | `UnsupportedVerificationProcessException` | That verification process is not supported for your account's country. | Contact Ripio. |
| `20007` | 400 | `KycNotApprovedException` | The customer's KYC is not approved. On [Check KYC](https://docs.ripio.com/ramps-api/kyc/reusable-kyc.md), no reusable approved KYC exists. | Complete the KYC flow first. |
| `20008` | 400 | `KycServiceStartValidationException` | The verification process could not be opened; `detail` carries the reason. | Check `detail` and retry. |
| `20009` | 400 | `KycServiceValidatePersonalDataException` | The customer's personal data was rejected. | Correct it and retry. |
| `20010` | 400 | `KycServiceValidateAddressDataException` | The customer's address data was rejected. | Correct it and retry. |
| `20011` | 400 | `KycServiceValidateExtraDataException` | The additional, country-specific data was rejected. | Check [the fields by country](https://docs.ripio.com/ramps-api/kyc/kyc-fields-by-country.md). |
| `20012` | 400 | `KycServiceSetupProviderException` | The verification could not be handed off to the identity-verification step. | Retry; if it persists, contact Ripio support. |
| `20013` | 400 | `InvalidOtpException` | The OTP code is invalid or expired. | Ask the customer for a new code. |
| `20015` | 400 | `KycAlreadyApprovedException` | The customer's KYC is already approved. | No new verification is needed. |
| `20018` | 400 | `KycServiceValidatePhoneDataException` | The customer's phone data was rejected. | Correct it and retry. |
| `20019` | 400 | `KycServiceSubmitValidationFilesException` | The identity documents or photos were rejected. | Upload them again. |
| `20020` | 400 | `KycServiceValidateTermsDataException` | The terms-acceptance data sent with the KYC was rejected. | Check it and retry. |
| `20031` | 400 | `MissingKYCRedirectUrlException` | A `redirectUrl` is required. | Send it, or ask Ripio to configure a default for your account. |
| `20047` | 400 | `KycOtpValidationNotPendingException` | The KYC submission is not waiting for a code. | Continue with the next step of the flow. |
| `20062` | 400 | `KycProcessLimitExceededException` | Your account reached its KYC process limit. | Contact Ripio. |
| `20065` | 403 | `KycProviderTokenSharingNotEnabledException` | KYC token sharing is not enabled for your account. | Contact Ripio, or run the standard flow. |
| `20091` | 400 | `KycServiceResendEmailOtpException` | The email verification code could not be resent. | Retry. |
| `20092` | 400 | `KycServiceValidateEmailOtpException` | The email verification code was rejected. | Ask the customer for the right code. |
| `20093` | 400 | `KycUnifiedFlowRequiredException` | Your account uses the unified KYC flow. | Use `/kyc/start/` and `/kyc/otp/*` instead. |
| `20094` | 400 | `KycEmailOtpNotConfirmedException` | The customer's email code has not been validated yet. | Validate it before submitting the KYC data. |
| `20095` | 403 | `KycUnifiedFlowNotEnabledException` | The unified KYC flow is not enabled for your account. | Use the standard flow. |
| `40008` | 400 | `CheckKycRequiredException` | Your account reuses existing KYCs. | Call [Check KYC](https://docs.ripio.com/ramps-api/kyc/reusable-kyc.md) before starting a new one. |

## Fiat accounts

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20002` | 400 | `InvalidFiatAccountTypeException` | There are no account requirements for this payment method. | Check `paymentMethodType`. |
| `20005` | 400 | `ExternalFiatAccountNotEnabledException` | The fiat account is not `enabled`, so it cannot be used yet. | See the [fiat account lifecycle](https://docs.ripio.com/ramps-api/fiat-accounts/lifecycle.md). |
| `20021` | 400 | `InvalidFiatAccountDataException` | The bank reports that the destination account does not exist. | Check the account data. |
| `20034` | 400 | `InvalidFiatAccountCurrencyException` | The destination account's currency is not supported. | Register an account in the operation's currency. |
| `20059` | 400 | `ExternalFiatAccountSameAsOriginException` | The destination account is the customer's own deposit account. | Register a different account. |
| `20079` | 400 | `FiatAccountKeyNotFoundException` | The destination key or alias does not exist. | Correct the value. |
| `20080` | 400 | `FiatAccountKeyNotUsableException` | The destination key exists but cannot receive transfers right now. | The customer has to fix the key's state at their bank. |
| `20089` | 400 | `FiatAccountDestinationBankNotSupportedException` | Mexico: the bank the CLABE belongs to cannot receive payouts. | Register an account at another bank. |
| `40011` | 404 | `ExternalFiatAccountNotFoundException` | The fiat account does not exist or does not belong to this customer. | Check `fiatAccountId`. |
| `40013` | 400 | `InvalidExternalFiatAccountStatusException` | The fiat account's status does not allow this operation (for example confirming one that is not `unconfirmed`). | See the [fiat account lifecycle](https://docs.ripio.com/ramps-api/fiat-accounts/lifecycle.md). |
| `40014` | 400 | `FiatAccountNotReadyException` | The customer's deposit account exists but is not ready yet. | Retry once it is `enabled`. |
| `40018` | 400 | `FiatAccountPrerequisiteNotReadyException` | The customer needs a ready deposit account for this payment method before a destination account can be added. | [Create the deposit account](https://docs.ripio.com/ramps-api/customers/create-deposit-account.md) and wait until it is `enabled`. |
| `40019` | 400 | `FiatAccountNotCreatedException` | The customer has no deposit account for this payment method. | [Create it](https://docs.ripio.com/ramps-api/customers/create-deposit-account.md) and wait until it is `enabled`. |

## Quotes, on-ramp and off-ramp

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20006` | 403 | `QuoteWithNoPrice` | The quote has no price available. | Request a new quote. |
| `20016` | 403 | `PaymentMethodNotAllowedForTransactionException` | This payment method cannot be used for on-ramp sessions. | Create a single on-ramp order instead. |
| `20017` | 403 | `PaymentMethodNotAllowedForAccountException` | This payment method is not enabled for your account. | Contact Ripio. |
| `20035` | 400 | `InvalidOrderStateException` | The order is not in a state that allows this operation. | See [Change Fiat Account](https://docs.ripio.com/ramps-api/off-ramp/change-fiat-account.md). |
| `20060` | 400 | `IncompatibleFiatAccountTypeException` | The new fiat account's payment method does not match the order's. | Use an account with the same `paymentMethodType`. |
| `20103` | 400 | `WithdrawalNetworkNotAvailableException` | The currency cannot be withdrawn over that network for your account. | Pick a network from the available withdrawal networks. |
| `20104` | 400 | `QuoteNetAmountNotPositiveException` | Fees exceed the quoted amount, so nothing would be left. | Quote a larger amount. |
| `20108` | 400 | `TravelRuleRequiredException` | Mexico: the operation needs a Travel Rule declaration. | Send `travelRule` — see [Travel Rule (Mexico)](https://docs.ripio.com/ramps-api/travel-rule/introduction.md). |
| `20114` | 400 | `ExternalFiatAccountProviderMismatchException` | The fiat account was registered for a different payment route than the operation's. | Register the account again with [Create Fiat Account](https://docs.ripio.com/ramps-api/fiat-accounts/create-fiat-account.md) and use the new `fiatAccountId`. |

## Refunds

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20042` | 404 | `DepositNotFoundException` | The order has no received fiat deposit to refund. | Check the order. |
| `20044` | 400 | `DepositAlreadyRefundedException` | The deposit was already refunded, or its refund has already started. | Nothing to do. |
| `20048` | 400 | `DepositOrderNotRefundableException` | Only deposits of cancelled orders whose trade did not execute can be refunded. | Check the order's status. |
| `20050` | 400 | `InvalidFiatAccountPaymentMethodException` | The account's payment method is not enabled, or not supported for this operation. | Use an account with a supported payment method. |
| `20054` | 409 | `CryptoRefundNotAllowedRequestException` | A crypto refund cannot be requested in the order's current state. | See [Refunds](https://docs.ripio.com/ramps-api/refunds/overview.md). |
| `20055` | 409 | `CryptoRefundAmountBelowMinException` | The deposited amount is below the minimum that can be refunded. | Contact Ripio support. |
| `20056` | 403 | `FiatRefundNotEnabledException` | Fiat refunds are not enabled for your account. | Contact Ripio. |
| `20057` | 409 | `FiatRefundAlreadyExistsException` | A refund already exists for this deposit. | Ripio support handles it. |
| `20067` | 400 | `FiatAccountRequiredForRefundException` | This deposit can only be refunded to a destination account. | Send `fiatAccountId`. |
| `20068` | 400 | `FiatAccountNotAllowedForRefundException` | This deposit is refunded to its origin account. | Do not send `fiatAccountId`. |
| `20069` | 400 | `RefundToOriginNotPossibleException` | The deposit cannot be returned to its origin account. | Contact Ripio support. |
| `20070` | 400 | `PartnerRefundNotSupportedForProviderException` | Refunds are not supported for this deposit's payment method. | Contact Ripio support. |
| `20072` | 403 | `CryptoRefundNotEnabledException` | Crypto refunds are not enabled for your account. | Contact Ripio. |
| `20074` | 400 | `CryptoRefundAddressNotAllowedException` | Your account refunds crypto to the origin address. | Do not send `refundAddress`. |
| `20077` | 409 | `CryptoRefundDepositPendingMatchException` | The crypto deposit may still be matched to an order. | Retry later. |

## QR payments (Sell and Pay)

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20023` | 400 | `SellAndPayExpiredException` | The QR payment has expired. | Start a new one. |
| `20024` | 400 | `SellAndPayInvalidStatusForUpdateException` | The QR payment's status does not allow updates. | Check its status. |
| `20025` | 400 | `InvalidSellAndPayAmountException` | The amount is not valid for this QR payment. | Correct the amount. |
| `20026` | 400 | `SellAndPayStatusCannotBeCanceledException` | The QR payment can no longer be cancelled. | Check its status. |
| `20027` | 400 | `RequiredSellAndPayDepositNetworkException` | A deposit network is required for the selected currency. | Send the network. |
| `20028` | 400 | `InvalidSellAndPayDepositNetworkException` | The deposit network is not valid. | Pick a supported network. |
| `20029` | 400 | `InvalidSellAndPayDepositCurrencyNetworkException` | The currency is not supported on the selected network. | Pick a supported currency and network pair. |
| `20030` | 400 | `SellAndPayInvalidStatusForExecutionException` | The QR payment's status does not allow execution. | Check its status. |
| `20032` | 400 | `PaymentOrderCreationException` | The payment order for the QR could not be created; `detail` explains why. | Check `detail`. |
| `20033` | 400 | `InvalidQRCodeException` | The QR code is invalid or not supported. | Scan it again. |
| `20038` | 409 | `ActiveSellAndPayExistsException` | The customer already has a QR payment in progress. | Finish or cancel it first. |
| `20049` | 400 | `SellAndPayFiatAccountNotRequiredException` | QR payments in this country do not need a customer fiat account. | Skip this step. |
| `20051` | 400 | `NoEnabledFiatAccountForCurrencyException` | The customer has no enabled fiat account for the payment currency. | Register and enable one. |
| `20052` | 400 | `SellAndPayAmountBelowMinSellLimitException` | The amount is below your account's minimum. | Increase the amount. |
| `20053` | 400 | `SellAndPayAmountAboveMaxSellLimitException` | The amount is above your account's maximum. | Reduce the amount. |
| `40016` | 404 | `SellAndPayNotFoundException` | The QR payment was not found. | Check the identifier. |

## Support tickets

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20061` | 403 | `SupportTicketsNotEnabledException` | Support tickets are not enabled for your account. | Contact Ripio. |
| `40017` | 404 | `SupportTicketNotFoundException` | The support ticket was not found. | Check the identifier. |

## Sandbox only

| Code | Status | Type | Meaning | What to do |
| :- | :- | :- | :- | :- |
| `20084` – `20088` | 400 | `Kyc…` | KYC decision simulation errors. | See [KYC in sandbox](https://docs.ripio.com/ramps-api/sandbox/kyc-in-sandbox.md). |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.