Payout error codes

This page describes error codes for API version 2024-01-31 or later. For older API versions, please see Error codes (older versions).

All the possible errors associated with the HTTP 400 status code while creating/managing payouts and beneficiaries via our API endpoints are listed in this page.

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`	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 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; `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
`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
`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.	-

Confirm funding for a payout

Error codes, detailed descriptions, and parameters for Confirm funding for 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.	-
`confirm_funding_unsupported`	Your account is not set up with manual-funding mode. No funding instruction is required. See Fund deduction to learn more.	-
`funding_already_confirmed`	The funding for this payout has already been confirmed. You can only confirm funding for a payout when funding status is `REQUIRES_FUNDING_CONFIRMATION`. See Funding statuses to learn more.	-

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 the `SENT` 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-100) 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 API with 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 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.	-
`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 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	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.