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