Error codes (older versions)
This page lists all the possible error code values before API version 2024-01-31 and error response structures before API version 2024-09-27.
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 Transfers & Beneficiaries API endpoints. For errors with transfers to Airwallex accounts specifically, please see Errors for transfers 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 transfers to Airwallex accounts specifically, please see Errors for transfers to Airwallex accounts.
400 errors
Create a transfer
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 transfer. Top up your Wallet balance or provide a lower amount. | - |
beneficiary_type_unsupported | Sending transfers to this beneficiary account with the specified transfer details is not supported. Please contact your Account Manager and report this issue. | - |
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 transfers to domestic beneficiaries. Declaration has not been completed. Learn more about the requirements here . | - |
fee_unknown | There is a problem with your transfer 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 transfer is insufficient. Valid orders equivalent to the transfer 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 transfer have not settled. Valid orders equivalent to the transfer 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 transfers with the same source and payment currency, you can provide a date within 120 days from the current date; for transfers 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; amount_max_currency: currency of the maximum amount limit |
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 |
transfer_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 transfer 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 transfer 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 transfer before which was created successfully (payment_id included in params). Please use a different request ID if you wish to create a separate transfer. | payment_id: ID of the transfer with the same request ID |
request_id_used | The request ID has been used before but the transfer was not created successfully. Please use a different request ID to create the transfer. | - |
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 |
workflow_invalid | The active transfer approval workflow is invalid. Inform account owner or account admin users to review the active workflow in the web app. | - |
Retry a transfer
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. | - |
transfer_not_found | The payment_id specified cannot be found. Please try again with a valid payment ID. | - |
retry_unsupported | The transfer in the current status cannot be retried. You can only retry a transfer that is in the FAILED status and was not initially created and submitted for approval. See Transfer statuses to learn more. | - |
service_unavailable | Service is unavailable at this moment. Please try again later. | - |
Cancel a transfer
Error codes, detailed descriptions, and parameters for Cancel a payment API.
| Code | Description | Parameters |
|---|---|---|
transfer_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 transfer in the current status cannot be cancelled. You can only cancel a transfer in NEW or FAILED status. See Transfer statuses to learn more. | - |
Validate a transfer, 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 | Both payment_amount and source_amount are specified. Please only provide 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 higher 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 transfers 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 support@airwallex.com 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. | - |
090 | This field cannot only contain spaces. | - |
091 | Neither iban nor bank_code & account_number is provided under beneficiary.bank_details. Please specify value(s) for either type of details and try again. | - |
092 | Provide a valid phone number in the format of +aaa-nnnnnnn where the aaa is an international country code up to 3 digits, and nnnnnnn is a local phone number up to 14 digits. E.g. +1-1234567890 | - |
099 | On top of the basic format requirement under 092, the country code substring within the phone number should be as suggested in the "params" object. | country_code: acceptable values for the substring |
100 | On top of the basic format requirement under 092, the length of the local phone number substring after the region code should be within the range suggested in the "params" object. | length_min: minimum digit number accepted for the substring; length_max: maximum digit accepted for the substring |
Transfer-method-specific validation errors
| Code | Transfer method | Description | Parameters |
|---|---|---|---|
051 | Australia BPAY | The BPAY biller code specified is invalid. Please provide a valid biller code and try again. | - |
052 | Australia BPAY | 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 | Australia BPAY | The BPAY Customer Reference Number (CRN) specified is invalid for this Biller. | - |
054 | Australia BPAY | The length of the BPAY Customer Reference Number (CRN) specified is not acceptable for this Biller. | - |
055 | Australia BPAY | Only numeric values are accepted. Please remove any special characters such as "," or "$" and try again. | - |
056 | Australia BPAY | 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 | Australia BPAY | 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 | Australia BPAY | The payment amount specified is incorrect and not accepted by the Biller. Check the Biller's requirement and provide a valid amount. | - |
059 | Australia BPAY | The payment date specified is invalid. Check the Biller's requirement and provide a valid date. | - |
060 | Brazil LOCAL | The personal identification number should consist of 8 numeric or 9 alphanumeric characters (definition). | - |
061 | Brazil LOCAL | The personal identification number should start with an "E" followed by up to 8 numeric characters. | - |
062 | Brazil LOCAL | This should be 4 digits, or 4 digits followed by 1 alphanumeric character (definition). You may include a hyphen. | - |
063 | Brazil LOCAL | This should be 4 digits. | - |
064 | Brazil LOCAL | This should be 4 digits, or 4 digits followed by a 1-digit suffix. You may include a hyphen. | - |
065 | Brazil LOCAL | This should be 4 digits, or 4 digits followed by a 1-2 alphanumeric character (definition) suffix. You may include a hyphen. | - |
066 | Brazil LOCAL | 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 | Brazil LOCAL | This should be 8 digits followed by a 1-digit suffix. You may include a hyphen. | - |
068 | Brazil LOCAL | This should be 11 digits followed by a 1-digit suffix. You may include a period and a hyphen. | - |
069 | Brazil LOCAL | This should be 11 to 12 digits followed by a 1-digit suffix. You may include a period and a hyphen. | - |
070 | Brazil LOCAL | This should be 7 digits, or 7 digits followed by a 1-digit suffix. You may include a hyphen. | - |
071 | Brazil LOCAL | 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 | Brazil LOCAL | This should be 5 digits followed by a 2-digit suffix. You may include a hyphen. | - |
073 | China LOCAL | 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 | China LOCAL | The ID number specified is invalid. | - |
075 | China LOCAL | The bank account number specified is invalid for the corresponding bank. Please provide a valid bank account number and try again. | - |
076 | China LOCAL | The bank account name should match the first and last name in Chinese. | - |
077 | China LOCAL | The beneficiary cannot be a financial institution. | - |
078 | China LOCAL | 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 | China LOCAL | 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. | - |
093 | Paraguay LOCAL | Provide a valid 9-digit Registro Único del Contribuyente (RUC) as registered with the bank, starting with "800". | - |
095 | China LOCAL | Provide matching Account name and Chinese national ID number that belong to one of your Airwallex account's Ultimate Beneficial Owners when paying to this bank. | - |
096 | China LOCAL | Enable Data sharing (in Ariwallex WebApp under Connections) in order to pay to this bank. | - |
097 | China LOCAL | Confirm that you have enbaled eCommerce Collection Service for the beneficiary account (in Ariwallex WebApp under Connections) in order to pay to this bank. | - |
098 | Canada INTERAC | A set of security question and answer is required because this email address is not registered with Interac e-Transfer autodeposit. Please specify the security_question and security_answer, and share them with your beneficiaries. Learn more in Canada country guide. | - |
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 transfers to an account under the same name as yours. | - |
081 | FX Forward currency conversion is unsupported for transfers 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 transfers 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 transfer 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 transfer to an Airwallex account which was created successfully. Please use a different request ID if you wish to create a separate transfer. | wallet_transfer_id: ID of the transfer to an Airwallex account with the same request ID |
transfer_currency_unsupported | The transfer 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 transfers to an Airwallex account
| Code | Description | Parameters |
|---|---|---|
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. |