Error codes

Last updated: December 11, 2024

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.

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. `{CURRENCY}` represents a three-letter ISO 4217 currency code. For example, `usd_currency_not_configured`.
`{SCHEME}_scheme_not_configured`	The specified scheme is not configured. `{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 is invalid.
`country_invalid`	The two-letter ISO country code of the payment source owner's billing 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 three-letter ISO currency code is invalid.
`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.
`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.
`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 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.
`recipient_account_number_required`	The recipient's account number is required.
`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 postcode is required.
`recipient_zip_required`	The first part of the recipient's UK postcode 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, please contact our Support team at [email protected].
`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. Read more about split payments.
`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 postcode is invalid.

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.

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

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 of its PayFac/Marketplace.
`principal_address_country_invalid_for_processing_scope`	The principal address country provided for the sub-entity is outside 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` For example, `legal_name_required` or `representatives_0_first_name_required`.	The specified field is mandatory but was not provided in the request: the field is null, contains empty strings, or contains white spaces.
`<field_name>_invalid` For example, `legal_name_invalid` or `profile_urls_0_invalid`.	The specified field does not match the validation policies for minimum length, maximum length, or formatting.

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.

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.

Error codes

Payments endpoint

Field validation errors

Accounts endpoint

Tokens endpoint

Instruments endpoint