Batch transfer error codes

Batch transfer errors

All possible batch-level errors while creating/managing batch transfers via Batch Transfer API endpoints API are listed in this section. Like the example below, the response you receive will contain:

• code: A semantic code specifying the error encountered;
• source: This indicates the procedure where the error is encountered, e.g. transfer or conversion; or the specific parameter with error, e.g. request_id;
• message: A brief statement that explains the code. For detailed handling instructions of each error, please see the description in tables below;
• details: An object containing further details where applicable for you to handle.

Depending on the error code, the details object contains different parsable information. For a batch-level error, it will contain the relevant request parameter(s) and their value if applicable. See the example below.

1{
2    "code": "batch_request_id_duplicate",
3    "details": {},
4    "message": "The request ID has been used to a batch before which was created successfully. Please use a different request ID if you wish to create a separate batch transfer.",
5    "source": "batch_request_id_duplicate"
6}

Create a batch transfer

Error codes, detailed descriptions, and parameters for Create a batch transfer API.

Add items to a batch

Error codes, detailed descriptions, and parameters for Add items to a batch API.

Quote a batch transfer

Error codes, detailed descriptions, and parameters for Quote a batch transfer API.

Submit a batch transfer

Error codes, detailed descriptions, and parameters for Submit a batch transfer API.

Delete a batch transfer

Error codes, detailed descriptions, and parameters for Delete a batch transfer API.

Batch transfer item errors

All possible batch item-level errors while adding items or booking a batch are listed below.

Validation errors for a batch item

If a batch item fails the schema validation, the batch item status will transition to VALIDATION_FAILED. Like 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.

1  {
2   "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e12",
3   "request_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e13",
4   "transfer_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e14",
5   "status": "VALIDATION_FAILED",
6   "errors": [{
7       "source": "beneficiary.address.street_address",
8       "code": "002",
9       "params": {
10           "length_min": 5,
11           "length_max": 200,   
12       }
13   }],
14   "updated_at": "2022-10-31T14:00:00+0000"
15 }

You may find all item validation errors in Field validation errors for payouts.

Booking errors for a batch item

If a batch item fails to be booked, the batch item status will transition to BOOKING_FAILED. An error response example is shown below.

1  {
2   "id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e12",
3   "request_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e13",
4   "transfer_id": "d9af1614-a6a1-4d45-aae7-6858fc6d9e14",
5   "status": "BOOKING_FAILED",
6   "errors": [{
7       "code": "service_unavailable",
8       }
9   }],
10   "updated_at": "2022-10-31T14:00:00+0000"
11 }

All possible item-level booking error codes are listed below.

Direct debit deposit errors (asynchronous)

If the batch transfer is funded via direct debit from Linked Account, the funds will generally take 2-11 business days to settle (Learn more about direct debit flight times). If the deposit is rejected as it failed validation by either Airwallex or the banking scheme, the funding status will transition to FAILED and the funds will be returned to your external bank account. Please note that this type of error is asynchronous.

For a direct debit deposit with a failure status, the funding object in the response contains a failure_details object with:

• code: Error code for this direct debit deposit

• iso_code: Error code according to ISO 20022 standards

• provider_failure_details: If the error originated from the local clearing system, the response will contain this object with:

  • local_clearing_system: name of the direct debit scheme e.g. United Kingdom Bacs (UK_BACS)
  • code: error code directly from the clearing system
  • message: error message directly from the clearing system

The failure_reason field is also included for backward compatibility.

We recommend using the Airwallex error code or the iso_code for systematic exception handling. The code from provider_failure_details can be used for troubleshooting against the clearing system rules, but it is not advised for systematic handling because the clearing system may update it from time to time.

For scheme-specific errors that could be returned under provider_failure_details, refer to Direct debit deposit error codes.

General error codes

Example response

1{
2    "funding": {
3        "deposit_type": "DIRECT_DEBIT",
4        "funding_source_id": "ff621b96-9ee9-4429-9dd7-9defef411d11",
5        "status": "FAILED",
6        "failure_reason": "The transaction is rejected for regulatory reasons.",
7        "failure_details": {
8            "code": "regulatory_reason",
9            "iso_code": "RR04"
10        }
11    },
12    "id": "378e0df8-2c64-460b-921a-9ee69fdd38cd",
13    "metadata": {
14        "id": "5"
15    },
16    "name": "batch-name",
17    "quote_summary": {
18        "expires_at": "2024-03-04T03:09:05+0000",
19        "last_quoted_at": "2024-03-04T03:06:05+0000",
20        "quotes": [
21            {
22                "amount_beneficiary_receives": 100.0,
23                "amount_payer_pays": 100.0,
24                "fee_amount": 0,
25                "fee_currency": "AUD",
26                "transfer_currency": "AUD",
27                "source_currency": "AUD"
28            },
29            {
30                "amount_beneficiary_receives": 200.0,
31                "amount_payer_pays": 308.12,
32                "client_rate": 0.649109,
33                "currency_pair": "AUDUSD",
34                "fee_amount": 0,
35                "fee_currency": "AUD",
36                "transfer_currency": "USD",
37                "source_currency": "AUD"
38            }
39        ]
40    },
41    "remarks": "Any information",
42    "request_id": "8be90dda-cce4-4c70-b5b8-bcff408f599f",
43    "short_reference_id": "B240304-3GK4EPI",
44    "status": "SCHEDULED",
45    "total_item_count": 4,
46    "transfer_date": "2024-03-04",
47    "updated_at": "2024-03-04T03:06:05+0000",
48    "valid_item_count": 3
49}