Error codes

This page lists all the possible errors associated with the HTTP 400 status code while creating/managing payouts and beneficiaries via our API endpoints.

For 400 errors, the response you receive will contain a code specifying the error encountered. Depending on whether it is a general error or a field validation error, it may contain a params object or an errors object with additional parsable information which helps you handle exceptions systematically.

General errors with example response

A general error provides a response where code is not validation_failed. Like in the example below, an error response could contain a params object with additional parsable information, e.g. related payment_id.

JSON

See 400 errors for all potential error codes and descriptions, organized by corresponding Payouts & Beneficiaries API endpoints. For errors with payouts to Airwallex accounts specifically, please see Errors for payouts to Airwallex accounts.

Field validation errors with example response

A field validation error provides a response where code is validation_failed. This means that the request has failed schema validation. Like in the example below, the response contains an errors object with:

source: The specific field within the request that has failed schema validation.
code: Unique numeric identifier of the specific validation error encountered.
params: Additional parsable information relating to the specific validation error where applicable, e.g. minimum and maximum character length.

JSON

See Field validation errors to learn about all possible codes and applicable parameters. For errors with payouts to Airwallex accounts specifically, please see Errors for payouts to Airwallex accounts.

400 errors

Create a payout

Error codes, detailed descriptions, and parameters for Create a new payment API and Validate payment API.

Code	Description	Parameters
`validation_failed`	The request failed our schema validation. Refer to the `errors` object for erroneous fields, codes and parameters. See Validation errors for detailed descriptions.	-
`amount_beneficiary_receives_above_cumulative_limit`	The amount beneficiary receives (payment amount less fees paid by beneficiary) is above the maximum cumulative limit as defined in the `params` object. Provide a lower amount (for Malaysian customers only).	`amount_bene_receives`: payment amount less fees paid by beneficiary (if applicable); `daily_amount_max`: the maximum daily cumulative limit for the amount beneficiary receives; `daily_amount_max_currency`: currency of the maximum daily cumulative amount limit
`amount_above_payment_method_limit`	The resultant payment amount is above the maximum limit for this payment method. Provide a lower source amount or payment amount. You can retrieve the transfer limits of all payment methods calling Get the form schema API.	`source_amount`: amount in source currency; OR `payment_amount`: amount in payment currency
`amount_beneficiary_receives_below_limit`	The amount beneficiary receives (payment amount less fees paid by beneficiary) is below the minimum limit. Provide a higher amount than the limit included in the `params` object.	`amount_bene_receives`: payment amount less fee paid by beneficiary if applicable; `amount_min`: the minimum limit for this field; `amount_min_currency`: currency of the minimum amount limit
`amount_below_payment_method_limit`	The resultant payment amount is below the minimum limit for this payment method. Provide a higher source amount or payment amount. You can retrieve the transfer limits of all payment methods calling Get the form schema API.	`source_amount`: amount in source currency; OR `payment_amount`: amount in payment currency
`balance_insufficient`	There is insufficient Wallet balance to fund this payout. Top up your Wallet balance or provide a lower amount.	-
`beneficiary_type_unsupported`	The `entity_type` specified for the beneficiary is not supported. You can refer to the dynamic schema API or call Get the form schema API to retrieve the supported entity type for all payment methods.	-
`currency_pair_invalid`	The currency pair you specified is not supported. You can refer to the dynamic schema API or call Get the form schema API to retrieve the supported currencies of all payment methods.	`source_currency`: currency of the source amount; `payment_currency`: currency of the payment amount
`declaration_required`	Due to mainland China regulations, declaration is required for local payouts to domestic beneficiaries. Declaration has not been completed. Learn more about the requirements here .	-
`fee_unknown`	There is a problem with your payout fee configuration. Please contact the Account Manager.	-
`open_position_limit_exceeded`	The payment amount exceeds the remaining open position limit under the post fund model. Provide a lower amount or top up your Wallet balance. See here to learn more about funding models.	-
`order_amount_insufficient`	Orders for your China local payout is insufficient. Valid orders equivalent to the payout amount is required per local regulations. Learn more about uploading orders by connecting to marketplaces via token authorization here or calling Upload order items API.	-
`order_info_unsupported`	The `order_info` field is no longer supported. Please remove this field and try again.	-
`order_reconciliation_failed`	Orders for your China local payout have not settled. Valid orders equivalent to the payout amount is required per local regulations. Please try again later.	-
`payer_unsupported`	Payer specification is not supported. Please remove this field and try again.	-
`payment_currency_unsupported`	The currency of the payment amount is not supported. You can refer to the dynamic schema API or call Get the form schema API to retrieve the support currencies for all payment methods.	`payment_currency`: currency of the payment amount
`payment_date_invalid`	The `payment_date` specified is invalid. For payouts with the same source and payment currency, you can provide a date within 120 days from the current date; for payouts involving currency conversions, please check with the account manager your valid date range.	-
`payment_amount_above_account_limit`	The payment amount is above the account maximum limit. Provide a lower amount than the limit included in the `params` object.	`payment_amount`: amount in payment currency; `amount_max`: the maximum limit for this field
`payment_amount_below_account_limit`	The payment amount is below the account minimum limit. Provide a higher amount than the limit included in the `params` object.	`payment_amount`: amount in payment currency; `amount_min`: the minimum limit for payment amount; `amount_min_currency`: currency of the minimum amount limit
`payout_method_unsupported`	Unsupported payment method. You can log in and refer to our dynamic schema API, or retrieve our API schema API to understand the supported payment methods for this account.	-
`quote_expired`	The `quote_id` you provided for the currency conversion has expired. Please provide a valid quote ID, or remove this field and try again if you would like to create the payout without using a LockFX quote.	-
`quote_id_invalid`	The `quote_id` you provided for the currency conversion is invalid. Please provide a valid quote ID, or remove this field and try again if you would like to create the payout without using a LockFX quote.	-
`quote_id_required`	A quote for the currency conversion is required to use LockFX. Please provide a quote ID and try again.	-
`request_id_duplicate`	The request ID has been used to a payout before which was created successfully (`payment_id` included in `params`). Please use a different request ID if you wish to create a separate payout.	`payment_id`: ID of the payout with the same request ID
`request_id_used`	The request ID has been used before but the payout was not created successfully. Please use a different request ID to create the payout.	-
`service_unavailable`	Service is unavailable at this moment. Please try again later.	-
`source_amount_above_account_limit`	The source amount is above the account maximum limit. Provide a lower amount than the limit included in the `params` object.	`source_amount`: amount in source currency; `amount_max`: the maximum limit for this field; `amount_max_currency`: currency of the maximum amount limit
`source_amount_below_account_limit`	The source amount is below the account minimum limit. Provide a higher amount than the limit included in the `params` object.	`source_amount`: amount in source currency; `amount_min`: the minimum limit for this field; `amount_min_currency`: currency of the minimum amount limit
`source_currency_unsupported`	The currency of the source amount is not supported. You can refer to the dynamic schema API or call Get the form schema API to retrieve the support currencies of all payment methods.	`source_currency`: currency of the payment amount

Retry a payout

Error codes, detailed descriptions, and parameters for Retry a payment API.

Code	Description	Parameters
`validation_failed`	The request failed our schema validation. Refer to the `errors` object for erroneous fields, codes and parameters. See Validation errors for detailed descriptions.	-
`payout_not_found`	The `payment_id` specified cannot be found. Please try again with a valid payment ID.	-
`retry_unsupported`	The payout in the current status cannot be retried. You can only retry a payout in `FAILED` status. See Payout statuses to learn more.	-
`service_unavailable`	Service is unavailable at this moment. Please try again later.	-

Cancel a payout

Error codes, detailed descriptions, and parameters for Cancel a payment API.

Code	Description	Parameters
`payout_not_found`	The `payment_id` specified cannot be found. Please try again with a valid payment ID.	-
`service_unavailable`	Service is unavailable at this moment. Please try again later.	-
`update_unsupported`	The payout in the current status cannot be cancelled. You can only cancel a payout in `NEW` or `FAILED` status. See Payout statuses to learn more.	-

Validate a payout, or create/validate/update beneficiaries/payers

Error codes, detailed descriptions, and parameters for Validate payment API, Create a new beneficiary API, Validate beneficiary API, Update existing beneficiary API, Create a new payer API, Validate payer API, and Update existing payer API.

Code	Description	Parameters
`validation_failed`	The request failed our schema validation. Refer to the `errors` object for erroneous fields, codes and parameters. See Validation errors for detailed descriptions.	-
`service_unavailable`	Service is unavailable at this moment. Please try again later.	-

Field validation errors

Please find below all possible field validation error codes (001-089) within the errors object for an error response where code is validation_failed, accompanied with detailed descriptions and definitions of parsable parameters (if applicable). Remember that all items in the errors object will be referenced to a source. To systematically retriev our validation rules, call Get the API schema API, or Get the form schema APIwith our proposed UI components`.

General field validation errors

Code	Description	Parameters
`001`	This field is mandatory for this request. Please specify a value and try again.	-
`002`	Only alphanumeric characters and punctuations (definition) are accepted.	-
`003`	Only alphanumeric characters (definition) and spaces are accepted.	-
`004`	Only alphanumeric characters (definition) are accepted.	-
`005`	Only alphanumeric characters (definition), dots and dashes are accepted.	-
`006`	Only Chinese characters and punctuation (definition) are accepted.	-
`007`	Only Chinese characters are accepted.	-
`008`	Only numerical values are accepted.	-
`009`	This field cannot only contain numeric characters.	-
`010`	Invalid value for this field. You can refer to our API reference API for field requirements of this endpoint, or retrieve the API schema API if it's a beneficiary field.	-
`011`	Invalid format for this field. You can refer to our API reference API for field requirements of this endpoint, or retrieve the API schema API if it's a beneficiary field.	-
`012`	This field cannot contain leading or trailing whitespace characters. Please remove and try again.	-
`013`	This field cannot contain whitespace characters. Please remove and try again.	-
`014`	This field cannot contain emojis. Please remove and try again.	-
`015`	Only positive numerical value is accepted.	-
`016`	The value in this field is invalid and can only be one of the acceptable value specified in the `params` object.	`value_options`: the acceptable values for this field
`017`	The value in this field is invalid. Refer to the acceptable value as defined in the `params` object.	`value`: acceptable value for this field
`018`	The number of characters in this field is higher/lower than the acceptable length. Please provide a value within the acceptable range as defined in the `params` object.	`length_min`: minimum number of characters accepted for this field; `length_max`: maximum number of characters accepted for this field
`019`	The number of characters in this field is higher/lower than the acceptable length. Please provide a value in the length as defined in the `params` object.	`length`: the exact number of characters accepted for this field
`020`	The number of characters in this field is lower than the acceptable length. Please provide a value longer than the minimum length as defined in the `params` object.	`length_min`: minimum number of characters accepted for this field
`021`	The number of characters in this field is higher than the acceptable length. Please provide a value shorter than the maximum length in the `params` object.	`length_max`: maximum number of characters accepted for this field
`022`	The number of characters in this field does not match the acceptable lengths. Please provide a value in the lengths as defined in the `params` object.	`length_options`: the acceptable number of characters for this field
`023`	The number of metadata keys should be smaller than 15, and the total number of metadata characters should be smaller than 4500.	-
`024`	The field `local_clearing_system` is not applicable for SWIFT `payment_method`. Please remove this field and try again.	-
`025`	The date and time should be in the ISO 8601 format.	-
`026`	The date should be in the ISO 8601 format.	-
`027`	The date specified is invalid. Please provide a valid date not earlier than today and try again.	-
`028`	Post Office Box address is not accepted. Please provide a valid street address.	-
`029`	Provide a valid email address.	-
`030`	Provide a valid postcode for the selected country/region.	-
`031`	The `account_currency` does not match the `payment_currency`. Please ensure the payment currency is supported by the beneficiary account.	-
`032`	The SWIFT code / BIC specified does not match the bank country code provided. Please provide a valid SWIFT code / BIC and try again.	-
`033`	The SWIFT code / BIC specified is invalid.	-
`034`	Neither `payment_amount` nor `source_amount` is specified. Please specify a value for either one and try again.	-
`035`	The bank code specified is invalid.	-
`036`	The IBAN specified does not match the bank country code provided. Please provide a valid IBAN and try again.	-
`037`	The payment amount is above the maximum limit. Provide a lower amount than the limit included in the `params` object.	`amount_max`: the maximum limit for this field; `amount_max_currency`: currency of the maximum amount limit
`038`	The payment amount is below the minimum limit. Provide a lower amount than the limit included in the `params` object.	`amount_min`: the minimum limit for this field; `amount_min_currency`: currency of the minimum amount limit
`039`	The beneficiary bank detail specified is invalid. Please provide valid details and try again.	-
`040`	The payment method specified is unsupported for this beneficiary. Please select a valid payment method and try again.	-
`041`	Paper check payouts is not enabled for this account.	-
`042`	The decimal places in this field are more than the acceptable format. Please provide a value with decimals less than the max number of decimal places as defined in the `params` object.	`decimal_max`: maximum number of decimal places accepted for this field
`043`	No payment method is supported for the selected payment currency and beneficiary bank country. You can retrieve our API schema API to understand the supported regions and currencies specific to your account.	-
`044`	The payer ID specified is invalid. Please provide a valid ID of an existing payer and try again.	-
`045`	The beneficiary ID specified is invalid. Please provide a valid ID of an existing beneficiary and try again.	-
`046`	The request cannot contain values in both beneficiary ID and beneficiary object. Please only specify either one or the other and try again.	-
`047`	The request cannot contain values in both payer ID and payer object. Please only specify either one or the other and try again.	-
`048`	Payer specification is not supported. Please remove this field and try again.	-
`049`	The payer is under/over the age requirement per local regulations. Please provide a payer within the acceptable age range as defined in the `params` object.	`age_min`: minimum age accepted for this field; `age_max`: maximum age accepted for this field
`050`	An unexpected error has occurred. Please contact the Account Manager or [email protected] to troubleshoot the error.	-
`082`	The branch code is invalid for the bank specified. Please provide a valid and supported branch code and try again.	-
`085`	This is not a valid bank account with the beneficiary bank specified. Please provide a valid account number and try again.	-
`086`	The bank code specified within the bank account number is invalid or unsupported. Please check the leading digits as suggested in the `params` object and try again. The value of `length` within the `params` object represents the number of leading digits within the bank account number that stands for the bank code.	`length`: the number of leading digits within the account number that stands for a bank code
`087`	The branch code specified within the bank account number is invalid or unsupported. Please check the leading digits as suggested in the `params` object and try again. The value of `length` within the `params` object represents the number of leading digits within the bank account number that stands for the branch code.	`length`: the number of leading digits within the account number that stands for a branch code
`088`	The transit number is invalid for the financial institution specified. Please check and try again.	-

Australia BPAY field validation errors

Code	Description	Parameters
`051`	The BPAY biller code specified is invalid. Please provide a valid biller code and try again.	-
`052`	The BPAY Customer Reference Number (CRN) specified should only contain numeric characters. Please remove any invalid characters such as "-" or spaces and try again.	-
`053`	The BPAY Customer Reference Number (CRN) specified is invalid for this Biller.	-
`054`	The length of the BPAY Customer Reference Number (CRN) specified is not acceptable for this Biller.	-
`055`	Only numeric values are accepted. Please remove any special characters such as "," or "$" and try again.	-
`056`	The payment amount specified is less than the minimum amount the Biller can accept. Check the Biller's requirement and provide a valid amount.	-
`057`	The payment amount specified is higher than the maximum amount the Biller can accept. Check the Biller's requirement and provide a valid amount.	-
`058`	The payment amount specified is incorrect and not accepted by the Biller. Check the Biller's requirement and provide a valid amount.	-
`059`	The payment date specified is invalid. Check the Biller's requirement and provide a valid date.	-

Brazil local payout field validation errors

Code	Description	Parameters
`060`	The personal identification number should consist of 8 numeric or 9 alphanumeric characters (definition).	-
`061`	The personal identification number should start with an "E" followed by up to 8 numeric characters.	-
`062`	This should be 4 digits, or 4 digits followed by 1 alphanumeric character (definition). You may include a hyphen.	-
`063`	This should be 4 digits.	-
`064`	This should be 4 digits, or 4 digits followed by a 1-digit suffix. You may include a hyphen.	-
`065`	This should be 4 digits, or 4 digits followed by a 1-2 alphanumeric character (definition) suffix. You may include a hyphen.	-
`066`	The number of digits should be the same as defined by `length_1` in parameters, or `length_2` digits followed by a 1-digit suffix. You may include a hyphen.	`length_1`: the number of numeric digits accepted for this field; `length_2`: the number of numeric digits accepted for this field when follow by a 1-digit suffix (e.g. "1" or "-1")
`067`	This should be 8 digits followed by a 1-digit suffix. You may include a hyphen.	-
`068`	This should be 11 digits followed by a 1-digit suffix. You may include a period and a hyphen.	-
`069`	This should be 11 to 12 digits followed by a 1-digit suffix. You may include a period and a hyphen.	-
`070`	This should be 7 digits, or 7 digits followed by a 1-digit suffix. You may include a hyphen.	-
`071`	This should be 5 digits followed by a 1-digit suffix, or 7 digits followed by a 1-digit suffix. You may include a hyphen.	-
`072`	This should be 5 digits followed by a 2-digit suffix. You may include a hyphen.	-

China local payout field validation errors

Code	Description	Parameters
`073`	The beneficiary is under/over the age requirement per local regulations. Please provide a beneficiary within the acceptable age range as defined in the `params` object.	`age_min`: minimum age accepted for this field; `age_max`: maximum age accepted for this field
`074`	The ID number specified is invalid.	-
`075`	The bank account number specified is invalid for the corresponding bank. Please provide a valid bank account number and try again.	-
`076`	The bank account name should match the first and last name in Chinese.	-
`077`	The beneficiary cannot be a financial institution.	-
`078`	The fields do not match the registered information for the bank account specified. Please provide matching beneficiary name, ID, bank account number and mobile number as registered on the bank account.	-
`079`	The fields do not match the registered information for the beneficiary specified. Please provide beneficiary business name, business registration number and legal representative name as registered with the local authorities.	-

Region-specific field validation errors

These errors only pertain to specific regions. Check with you Account Manager if they apply to you.

Code	Description	Parameters
`080`	FX Forward currency conversion is unsupported for payouts to an account under the same name as yours.	-
`081`	FX Forward currency conversion is unsupported for payouts to your own account.	-

IBAN validation errors

Code	Description	Parameters
`083`	The IBAN is invalid for the country specified. Please provide a valid IBAN and try again.	-
`084`	We are unable to validate this IBAN due to an unexpected error. Please try again later. If the problem persists, contact your Account Manager.	-
`089`	This IBAN belongs to a bank that we currently do not support. Please try again with another bank's account, or contact your Account Manager.	-

Character definitions

alphanumeric characters: A to Z, a to z, 0 to 9
punctuation: ! ” # $ % & ' ( ) * + , - . / : ; < = > ? @ [ \ ] ^ _ ' { | } ~

Errors for payouts to an Airwallex account

Error codes, detailed descriptions, and parameters for Create a new wallet transfer API.

Code	Description	Parameters
`balance_insufficient`	The Wallet balance is insufficient to fund this payout to an Airwallex account. Top up your Wallet or provide a lower amount.	-
`beneficiary_unavailable`	The `account_number` and `account_name` cannot be matched to an Airwallex account. Please check the beneficairy information you have obtained.	-
`request_id_duplicate`	The request ID has been used on a payout to an Airwallex account which was created successfully. Please use a different request ID if you wish to create a separate payout.	`wallet_transfer_id`: ID of the payout to an Airwallex account with the same request ID
`transfer_currency_unsupported`	The payout currency is not supported. Please make sure to pay in currencies that can be held in the Wallet: AUD, CAD, CHF, CNY, CZK, DKK, EUR, GBP, HKD, HUF, ILS, JPY, KRW, MXN, NOK, NZD, PLN, RON, SEK, SGD, THB, USD or ZAR.	-
`validation_failed`	The request failed our schema validation. Refer to the `errors` object for erroneous fields, codes and parameters. See the table below for detailed descriptions.	-

Field validation errors for payouts to an Airwallex account

Code	Description
001	This field is mandatory for this request. Please specify a value and try again.
011	Invalid value for this field. Please refer to our API reference API for the specific field requirements.
021	The number of characters in this field is higher than the acceptable length. Please provide a `reference` no more than 140 characters.