Search...
Log inGet started
Airwallex logo
Home
Core API
Payments
Transactional FX
Payouts
Issuing
Back to home
OverviewHow Airwallex Payouts workPayout network
Use cases
Errors
Error codes
Test and go live

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.

CodeDescriptionParameters
validation_failedThe 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_limitThe 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_limitThe 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_limitThe 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_limitThe 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_insufficientThere is insufficient Wallet balance to fund this payout. Top up your Wallet balance or provide a lower amount.-
beneficiary_type_unsupportedThe 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_invalidThe 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_requiredDue 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_unknownThere is a problem with your payout fee configuration. Please contact the Account Manager.-
open_position_limit_exceededThe 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_insufficientOrders 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_unsupportedThe order_info field is no longer supported. Please remove this field and try again.-
order_reconciliation_failedOrders 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_unsupportedPayer specification is not supported. Please remove this field and try again.-
payment_currency_unsupportedThe 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_invalidThe 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_limitThe 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_limitThe 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_unsupportedUnsupported 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_expiredThe 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_invalidThe 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_requiredA quote for the currency conversion is required to use LockFX. Please provide a quote ID and try again.-
request_id_duplicateThe 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_usedThe request ID has been used before but the payout was not created successfully. Please use a different request ID to create the payout.-
service_unavailableService is unavailable at this moment. Please try again later.-
source_amount_above_account_limitThe 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_limitThe 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_unsupportedThe 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.

CodeDescriptionParameters
validation_failedThe request failed our schema validation. Refer to the errors object for erroneous fields, codes and parameters. See Validation errors for detailed descriptions.-
payout_not_foundThe payment_id specified cannot be found. Please try again with a valid payment ID.-
retry_unsupportedThe payout in the current status cannot be retried. You can only retry a payout in FAILED status. See Payout statuses to learn more.-
service_unavailableService is unavailable at this moment. Please try again later.-

Cancel a payout

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

CodeDescriptionParameters
payout_not_foundThe payment_id specified cannot be found. Please try again with a valid payment ID.-
service_unavailableService is unavailable at this moment. Please try again later.-
update_unsupportedThe 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.

CodeDescriptionParameters
validation_failedThe request failed our schema validation. Refer to the errors object for erroneous fields, codes and parameters. See Validation errors for detailed descriptions.-
service_unavailableService 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

CodeDescriptionParameters
001This field is mandatory for this request. Please specify a value and try again.-
002Only alphanumeric characters and punctuations (definition) are accepted.-
003Only alphanumeric characters (definition) and spaces are accepted.-
004Only alphanumeric characters (definition) are accepted.-
005Only alphanumeric characters (definition), dots and dashes are accepted.-
006Only Chinese characters and punctuation (definition) are accepted.-
007Only Chinese characters are accepted.-
008Only numerical values are accepted.-
009This field cannot only contain numeric characters.-
010Invalid 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.-
011Invalid 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.-
012This field cannot contain leading or trailing whitespace characters. Please remove and try again.-
013This field cannot contain whitespace characters. Please remove and try again.-
014This field cannot contain emojis. Please remove and try again.-
015Only positive numerical value is accepted.-
016The 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
017The value in this field is invalid. Refer to the acceptable value as defined in the params object.value: acceptable value for this field
018The 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
019The 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
020The 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
021The 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
022The 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
023The number of metadata keys should be smaller than 15, and the total number of metadata characters should be smaller than 4500.-
024The field local_clearing_system is not applicable for SWIFT payment_method. Please remove this field and try again.-
025The date and time should be in the ISO 8601 format.-
026The date should be in the ISO 8601 format.-
027The date specified is invalid. Please provide a valid date not earlier than today and try again.-
028Post Office Box address is not accepted. Please provide a valid street address.-
029Provide a valid email address.-
030Provide a valid postcode for the selected country/region.-
031The account_currency does not match the payment_currency. Please ensure the payment currency is supported by the beneficiary account.-
032The SWIFT code / BIC specified does not match the bank country code provided. Please provide a valid SWIFT code / BIC and try again.-
033The SWIFT code / BIC specified is invalid.-
034Neither payment_amount nor source_amount is specified. Please specify a value for either one and try again.-
035The bank code specified is invalid.-
036The IBAN specified does not match the bank country code provided. Please provide a valid IBAN and try again.-
037The 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
038The 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
039The beneficiary bank detail specified is invalid. Please provide valid details and try again.-
040The payment method specified is unsupported for this beneficiary. Please select a valid payment method and try again.-
041Paper check payouts is not enabled for this account.-
042The 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
043No 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.-
044The payer ID specified is invalid. Please provide a valid ID of an existing payer and try again.-
045The beneficiary ID specified is invalid. Please provide a valid ID of an existing beneficiary and try again.-
046The request cannot contain values in both beneficiary ID and beneficiary object. Please only specify either one or the other and try again.-
047The request cannot contain values in both payer ID and payer object. Please only specify either one or the other and try again.-
048Payer specification is not supported. Please remove this field and try again.-
049The 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
050An unexpected error has occurred. Please contact the Account Manager or [email protected] to troubleshoot the error.-
082The branch code is invalid for the bank specified. Please provide a valid and supported branch code and try again.-
085This is not a valid bank account with the beneficiary bank specified. Please provide a valid account number and try again.-
086The 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
087The 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
088The transit number is invalid for the financial institution specified. Please check and try again.-

Australia BPAY field validation errors

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

Brazil local payout field validation errors

CodeDescriptionParameters
060The personal identification number should consist of 8 numeric or 9 alphanumeric characters (definition).-
061The personal identification number should start with an "E" followed by up to 8 numeric characters.-
062This should be 4 digits, or 4 digits followed by 1 alphanumeric character (definition). You may include a hyphen.-
063This should be 4 digits.-
064This should be 4 digits, or 4 digits followed by a 1-digit suffix. You may include a hyphen.-
065This should be 4 digits, or 4 digits followed by a 1-2 alphanumeric character (definition) suffix. You may include a hyphen.-
066The 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")
067This should be 8 digits followed by a 1-digit suffix. You may include a hyphen.-
068This should be 11 digits followed by a 1-digit suffix. You may include a period and a hyphen.-
069This should be 11 to 12 digits followed by a 1-digit suffix. You may include a period and a hyphen.-
070This should be 7 digits, or 7 digits followed by a 1-digit suffix. You may include a hyphen.-
071This should be 5 digits followed by a 1-digit suffix, or 7 digits followed by a 1-digit suffix. You may include a hyphen.-
072This should be 5 digits followed by a 2-digit suffix. You may include a hyphen.-

China local payout field validation errors

CodeDescriptionParameters
073The 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
074The ID number specified is invalid.-
075The bank account number specified is invalid for the corresponding bank. Please provide a valid bank account number and try again.-
076The bank account name should match the first and last name in Chinese.-
077The beneficiary cannot be a financial institution.-
078The 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.-
079The 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.

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

IBAN validation errors

CodeDescriptionParameters
083The IBAN is invalid for the country specified. Please provide a valid IBAN and try again.-
084We are unable to validate this IBAN due to an unexpected error. Please try again later. If the problem persists, contact your Account Manager.-
089This 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.

CodeDescriptionParameters
balance_insufficientThe Wallet balance is insufficient to fund this payout to an Airwallex account. Top up your Wallet or provide a lower amount.-
beneficiary_unavailableThe account_number and account_name cannot be matched to an Airwallex account. Please check the beneficairy information you have obtained.-
request_id_duplicateThe 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_unsupportedThe 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_failedThe 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

CodeDescription
001This field is mandatory for this request. Please specify a value and try again.
011Invalid value for this field. Please refer to our API reference API for the specific field requirements.
021The number of characters in this field is higher than the acceptable length. Please provide a reference no more than 140 characters.
On this page
  • 400 errors
  • Field validation errors
  • Errors for payouts to an Airwallex account