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:

{
  "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.
`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.
`20041`	400	`CustomerDeactivatedException`	The customer is deactivated and cannot operate.	See Reactivate Customer.
`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.	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 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 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, 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.
`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 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.
`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.
`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 and wait until it is `enabled`.
`40019`	400	`FiatAccountNotCreatedException`	The customer has no deposit account for this payment method.	Create it 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.
`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).
`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 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.
`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.

Overview

Widget integration

API Integration

General

Customers

Terms and Conditions and investor profile

Identity verification (KYC)

Fiat accounts

Quotes, on-ramp and off-ramp

Refunds

QR payments (Sell and Pay)

Support tickets

Sandbox only

​General

​Customers

​Terms and Conditions and investor profile

​Identity verification (KYC)

​Fiat accounts

​Quotes, on-ramp and off-ramp

​Refunds

​QR payments (Sell and Pay)

​Support tickets

​Sandbox only

General

Customers

Terms and Conditions and investor profile

Identity verification (KYC)

Fiat accounts

Quotes, on-ramp and off-ramp

Refunds

QR payments (Sell and Pay)

Support tickets

Sandbox only