# Error codes

After sending an API request, you will receive a response containing:

- an HTTP status code
- a response object containing a `response_code` that indicates the status of the request, or an error object containing one or several `error_codes`

This page describes the possible error codes you might receive. [View a list of the possible response codes](https://www.checkout.com/docs/resources/codes/api-response-codes.md).

---

## Payments endpoint

The following table lists the error codes that exist for the `/payments` endpoint.

| Name | Description |
| --- | --- |
| `{CURRENCY}_currency_not_configured` | The specified currency is not configured.<br><br>`{CURRENCY}` represents a three-letter ISO 4217 [currency code](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). For example, `usd_currency_not_configured`. |
| `{SCHEME}_scheme_not_configured` | The specified scheme is not configured.<br><br>`{SCHEME}` represents a card scheme. For example, `visa_scheme_not_configured`. |
| `3ds_malfunction` | 3DS has malfunctioned. |
| `3ds_not_configured` | 3DS is not configured. |
| `3ds_not_enabled_for_card` | 3DS is not enabled for card. |
| `3ds_not_supported` | 3DS is not supported. |
| `3ds_payment_required` | 3DS payment required. |
| `3ds_version_invalid` | The 3DS version is invalid. |
| `3ds_version_not_supported` | The 3DS version is not supported. |
| `action_failure_limit_exceeded` | The quota of failed payment actions has been exceeded. |
| `address_invalid` | The shipping address is invalid. |
| `aft_processor_not_matched` | Account funding transactions (AFTs) are not configured. A matching processor was not found. |
| `amount_exceeds_balance` | The payment amount exceeds the balance. |
| `amount_invalid` | The payment amount is invalid. |
| `amount_limit_exceeded` | The transaction to this card exceeded the amount limit set by the scheme's velocity limit. |
| `api_calls_quota_exceeded` | The quota for API calls has been exceeded. |
| `billing_descriptor_city_invalid` | The city from which the charge originated is invalid. |
| `billing_descriptor_city_required` | The city from which the charge originated is required. |
| `billing_descriptor_name_invalid` | The dynamic description of the charge is invalid. |
| `billing_descriptor_name_required` | A dynamic description of the charge is required. |
| `business_invalid` | The business settings are invalid. |
| `business_settings_missing` | The business settings are missing. |
| `capture_value_greater_than_authorized` | The capture value is greater than the authorized value. |
| `capture_value_greater_than_remaining_authorized` | The capture value is greater than the remaining authorized value. |
| `card_authorization_failed` | The card authorization has failed. |
| `card_disabled` | The card is disabled. |
| `card_expired` | The card is expired. |
| `card_expiry_month_invalid` | The two-digit expiry month is invalid. |
| `card_expiry_month_required` | A two-digit expiry month is required. |
| `card_expiry_year_invalid` | The four-digit expiry year is invalid. |
| `card_expiry_year_required` | A four-digit expiry year is required. |
| `card_holder_invalid` | The cardholder is invalid. |
| `card_not_eligible_domestic_money_transfer` | The recipient cardholder’s account is not eligible for domestic money transfer card payouts. |
| `card_not_eligible_cross_border_money_transfer` | The recipient cardholder’s account is not eligible for cross-border money transfer card payouts. |
| `card_not_eligible_domestic_non_money_transfer` | The recipient cardholder’s account is not eligible for domestic non-money transfer card payouts. |
| `card_not_eligible_cross_border_non_money_transfer` | The recipient cardholder’s account is not eligible for cross-border non-money transfer card payouts. |
| `card_not_eligible_domestic_online_gambling` | The recipient cardholder’s account is not eligible for domestic online gambling card payouts. |
| `card_not_eligible_cross_border_online_gambling` | The recipient cardholder’s account is not eligible for cross-border online gambling card payouts. |
| `card_not_found` | The card was not found. |
| `card_number_invalid` | The card number is invalid. |
| `card_number_required` | The card number is required. |
| `channel_details_invalid` | The channel details are invalid. |
| `channel_url_missing` | The channel URL is missing. |
| `charge_details_invalid` | The charge details are invalid. |
| `city_invalid` | The city from which the charge originated is invalid. |
| `country_address_invalid` | The first or second line of the payment source owner's billing address<br>is invalid. |
| `country_invalid` | The two-letter ISO country code of the payment source owner's billing<br>address is invalid. |
| `country_phone_code_invalid` | The international country calling code is invalid. |
| `country_phone_code_length_invalid` | The international country calling code length is invalid. |
| `currency_invalid` | The currency requested is not a valid ISO code.<br><br>Check that the currency in your request is one of the [currency codes we support](https://www.checkout.com/docs/developer-resources/codes/currency-codes.md). |
| `currency_required` | The three-letter ISO currency code is required. |
| `customer_already_exists` | The customer details already exist. |
| `customer_email_invalid` | The email address associated with the customer is invalid. |
| `customer_id_invalid` | The customer identifier is invalid. |
| `customer_not_found` | The customer's details cannot be found. |
| `customer_number_invalid` | The customer number is invalid. |
| `customer_plan_edit_failed` | Editing the customer plan has failed. |
| `customer_plan_id_invalid` | The customer plan identifier is invalid. |
| `cvv_invalid` | The CVV is invalid. |
| `destination_bank_not_found` | Bank code not recognized. Ensure the provided bank code is valid. |
| `destination_bank_details_invalid` | Invalid bank details provided. Check the request payload and ensure correct formatting. |
| `email_in_use` | The email address is already in use. |
| `email_invalid` | The email address is invalid. |
| `email_required` | The email address is required. |
| `endpoint_invalid` | The endpoint is invalid. |
| `estimated_authorization_not_supported` | Estimated authorization is not supported by the card issuer. <br><br><br>Estimated authorizations are supported on Visa and Mastercard, except for MOTO transactions. |
| `expiry_date_format_invalid` | The expiry date format is invalid. |
| `fail_url_invalid` | The failure URL is invalid. |
| `first_name_required` | The account holder's first name is required. |
| `last_name_required` | The account holder's last name is required. |
| `ip_address_invalid` | The IP address used to make the payment is invalid. |
| `issuer_network_unavailable` | The issuer network is unavailable. |
| `metadata_key_invalid` | The metadata key is invalid. |
| `no_authorization_enabled_processors_available` | There are no authorization processors configured. |
| `parameter_invalid` | The parameter is invalid. |
| `password_invalid` | The password is invalid. |
| `payment_expired` | The payment has expired. |
| `payment_invalid` | The payment is invalid. |
| `payment_method_not_supported` | The payment method is not supported.<br><br>You might need to set up a processor that supports the currency or scheme in your request. For example, if you request a payment in EUR but only have GBP enabled, the request fails. |
| `payment_source_required` | The payment source linked to a specific customer is required. |
| `payment_type_invalid` | The payment type is invalid. |
| `phone_number_invalid` | The phone number associated with the shipping address is invalid. |
| `phone_number_length_invalid` | The length of the phone number associated with the shipping address is<br>invalid. |
| `previous_payment_id_invalid` | The previous payment identifier is invalid. |
| `processing_error` | There was a general error when processing the request. If you encounter multiple failures, contact Checkout.com. |
| `processing_key_required` | The processing key is required. |
| `processing_value_required` | The processing value is required. |
| `recipient_account_number_invalid` | The recipient's account number is invalid, or it's too long for the scheme.<br><br>The maximum length depends on the scheme:<br><br>- Visa: 34 alphanumeric characters<br>- Mastercard: 50 digits (alphanumeric characters are not supported) |
| `recipient_account_number_required` | The recipient's account number is required. |
| `recipient_bank_details_invalid` | Invalid bank details provided. Check the request payload and ensure the formatting is correct. |
| `recipient_bank_not_found` | Bank code not recognized. Ensure the bank code provided is valid. |
| `recipient_dob_invalid` | The recipient's date of birth is invalid. |
| `recipient_dob_required` | The recipient's date of birth is required. |
| `recipient_last_name_required` | The recipient's last name is required. |
| `recipient_zip_invalid` | The first part of the recipient's UK post code is required. |
| `recipient_zip_required` | The first part of the recipient's UK post code is required. |
| `recurring_plan_exists` | The recurring plan exists. |
| `recurring_plan_not_exist` | The recurring plan does not exist. |
| `recurring_plan_removal_failed` | Removing the recurring plan has failed. |
| `request_invalid` | The request is invalid. |
| `request_json_invalid` | The JSON in the request is invalid. |
| `risk_enabled_required` | The risk check that is enabled is required. |
| `server_api_not_allowed` | The full API is not enabled on your sandbox account. To enable it, contact our [Support team](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). |
| `source_email_invalid` | The payment source owner's email address is invalid. |
| `source_email_required` | The payment source owner's email address is required. |
| `source_id_invalid` | The payment source identifier is invalid. |
| `source_id_or_email_required` | The payment source identifier or email address is required. |
| `source_id_required` | The payment source identifier is required. |
| `source_id_unknown` | The payment source identifier is unknown. |
| `source_invalid` | The payment source is invalid. |
| `source_or_destination_required` | The payment source or destination is required. |
| `source_token_invalid` | The Checkout.com token is invalid. |
| `source_token_required` | The Checkout.com token number is required. |
| `source_token_type_required` | The source token type is required. |
| `source_token_type_invalid` | The source token type is invalid. |
| `source_type_required` | The payment source type is required. |
| `sub_entities_count_invalid` | This account type cannot request a split payment for multiple sub-entities.<br><br>[Read more about split payments](https://www.checkout.com/docs/platforms/process-sub-entity-payments.md). |
| `success_url_invalid` | The success URL provided is invalid. |
| `token_expired` | The Checkout.com token has expired. |
| `token_in_use` | The Checkout.com token is in use. |
| `token_invalid` | The Checkout.com token is invalid. |
| `token_required` | The Checkout.com token is required. |
| `token_type_required` | The Checkout.com token type is required. |
| `token_used` | The Checkout.com token has already been used. |
| `velocity_amount_limit_exceeded` | The transaction to this card exceeded the amount limit set by the scheme's velocity limit. |
| `velocity_count_limit_exceeded` | The transaction to this card exceeded the transaction count limit set by the scheme's velocity limit. |
| `void_amount_invalid` | The void request amount is invalid. |
| `wallet_id_invalid` | The wallet identifier is invalid. |
| `zip_invalid` | The first part of the UK post code is invalid. |

### Field validation errors

When you send a request, Checkout.com validates the data type, format, and existence of the fields you provide to ensure they adhere to the specifications defined in the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

If there is an issue with a field, you'll receive an error code with the format:

`<OBJECT_NAME>_<VALIDATION_ERROR_TYPE>`

For example, if the value you provide for the `destination.account_holder.first_name` field contains too many characters, you'll receive the following error code:

`destination_account_holder_first_name_too_long`

The validation error types can be any of the following:

- `too_short`: the value you provided for the field contains too few characters
- `too_long`: the value you provided for the field contains too many characters
- `required`: the field is required but you did not provide a value
- `invalid_option`: you included a field in your request that is not a valid option
- `invalid_format`: the value you provided for the field is not in the correct format
- `invalid`: the field or value is invalid, due to factors not described by the other validation errors

---

## Accounts endpoint

The table below lists all the possible error codes you might receive when using the `/accounts/entities` endpoint.

| Name | Description |
| --- | --- |
| `profile_mccs_invalid_for_processing_scope` | The MCCs provided for the sub-entity are outside the processing scope<br>of its Payfac/Marketplace. |
| `principal_address_country_invalid_for_processing_scope` | The principal address country provided for the sub-entity is outside<br>the processing scope of its Payfac/Marketplace. |
| `client_entity_cannot_onboard_subentities` | The Payfac/Marketplace is not permitted to onboard new sub-entities. |
| `<field_name>_required`<br><br>For example, `legal_name_required` or `representatives_0_first_name_required`. | The specified field is required but was not provided in the request:<br>the field is null, contains empty strings, or contains white spaces. |
| `<field_name>_invalid`<br><br>For example, `legal_name_invalid` or `profile_urls_0_invalid`. | The specified field does not match the validation policies for minimum<br>length, maximum length, or formatting. |

---

## Tokens endpoint

The following table lists the error codes that exist for the `/tokens` endpoint.

| Name | Description |
| --- | --- |
| `processing_error` | There is a processing error. |
| `request_invalid` | The request is invalid. |
| `service_unavailable` | The service is unavailable. |
| `token_type_invalid` | The token type is invalid. |
| `token_data_invalid` | The token data is invalid. |
| `too_many_metadata_items` | The `metadata` object contains more than 20 key-value pairs. |
| `metadata_key_invalid` | A `metadata` key is an empty string. |
| `metadata_key_too_long` | A `metadata` key is longer than 100 characters. |
| `metadata_value_too_long` | A `metadata` value is longer than 100 characters. |
| `metadata_value_invalid` | A `metadata` value is `null`. |
| `metadata_only_supported_for_token_type_card` | `metadata` was provided for a token with a `type` other than `card`. |

---

## Instruments endpoint

The following table lists the error codes that exist for the `/instruments` endpoint.

| Name | Description |
| --- | --- |
| `identification_type_invalid` | The bank account instrument identification type is invalid. |
| `issuing_country_invalid` | The bank account issuing country type is invalid. |
| `date_of_birth_invalid` | The bank account date of birth type is invalid. |
| `country_of_birth_invalid` | The bank account country of birth type is invalid. |
| `country_required` | The bank account country is required. |
| `residential_status_invalid` | The bank account residential status is invalid. |
| `account_type_invalid` | The bank account type is invalid. |
| `account_holder_type_invalid` | The bank account holder type is invalid. |
| `iban_invalid` | The IBAN is invalid. |
| `swift_bic_invalid` | The SWIFT code is invalid. |
| `country_phone_code_invalid` | The country code is invalid. |
| `token_data_required` | The token data is required. |
| `instrument_already_has_customer` | A customer already exists for that instrument. |
| `entity_id_invalid` | The entity ID is invalid. |
| `too_many_metadata_items` | The `metadata` object contains more than 20 key-value pairs. |
| `metadata_key_invalid` | A `metadata` key is an empty string. |
| `metadata_key_too_long` | A `metadata` key is longer than 100 characters. |
| `metadata_value_too_long` | A `metadata` value is longer than 100 characters. |
| `metadata_value_invalid` | A `metadata` value is `null`. |