Error response codes

Airwallex uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP response codes and description

Code	Description
200	OK - The request was processed successfully
201	Created - The request was processed successfully
400	Error - The request was invalid, or an error occurred in Airwallex or downstream provider
401	Unauthorized - Please verify that the authentication token is provided and is valid
404	Not found - The requested endpoint or resource does not exist
500	There was an unexpected error on Airwallex's side. These should be rare

Error response structure

When we send an error response, the body will generally contain the following fields:

Name	Type	Description	Example
code	String	Error code	validation_error
source	String	Name of the request parameter that caused the error (This attribute is only for code validation_error)	merchant_order_id
message	String	Error message	merchant_order_id must be provided
trace_id	String	Trace ID of the API request for troubleshooting with Airwallex	e9afc11e3032ebaa4d4c9080ae77b232
details	Map	Contains additional information if present	Please see issuer_declined error response example below

Error codes for HTTP response code 400

Code	Message (subject to change)
3ds_not_supported	3DS is required, but 3DS is not supported by the card.
amount_above_limit	The operating amount `$amount` is above the limit `$limit`.
amount_below_limit	The operating amount `$amount` is below the limit `$limit`.
authentication_declined	The user failed authentication.
card_brand_not_supported	The card brand `$card_brand` is not supported.
configuration_error	Invalid request against merchant configuration. Please contact your account manager.
currency_not_supported	The currency `$currency` is not supported.
duplicate_request	The request ID `$id` has been used previously.
frequency_above_limit	The frequency limit of `$resource` is reached for operation `$operation`.
invalid_status_for_operation	The `$resource` status `$status` is invalid for operation `$operation`.
issuer_declined	The card issuer declined this transaction. Please refer to the original response code.
issuer_unavailable	The card issuer is temporarily unavailable. Please try again later.
no_3ds_liability_shift	Transaction declined since Liability shift couldn't not be achieved due to network outage or Issuer unavailability.
operation_not_supported	The operation `$operation` is not supported.
payment_method_not_allowed	The payment method is not enabled. Please contact your account manager.
provider_declined	The payment provider declined this transaction. Please refer to the original response code.
provider_unavailable	The payment provider is temporarily unavailable. Please try again later.
quote_expired	The quote has expired. Please create new quote and try again.
rejected_by_routing_rules	The transaction is rejected by merchant routing rules. Please contact your account manager.
resource_already_exists	The `$resource` with ID `$id` already exists.
resource_not_found	The `$resource` with ID `$id` cannot be found.
risk_declined	The transaction is blocked because of risk concern.
suspended_from_online_payments	The operating account has been suspended from processing online payments. Please contact your account manager.
validation_error	{message varies by validation rules}

Error codes for HTTP response codes 401, 404 and 500

Http response code	Code	Message
401	unauthorized	Access denied
404	not_found	The requested endpoint does not exist
404	resource_not_found	The `$resource` with ID `$id` cannot be found
500	internal_error	An internal error was encountered. Please try again later

Error response examples

validation_error

Shell

resource_not_found

Shell

internal_error

Shell

issuer_declined

Shell

Was this page helpful?