> For the complete documentation index, see [llms.txt](https://docs.neox.vn/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.neox.vn/docs/global/global-collections/integration/error-codes.md).

# Error Codes

Every Global Collections API response carries a `code` and a `message`. The `code` indicates the processing result; the `message` carries a human-readable description.

## Response codes

| Code | Status     | Description                                                     |
| ---- | ---------- | --------------------------------------------------------------- |
| 1    | SUCCESS    | The request was processed successfully.                         |
| 2    | FAILED     | An error occurred during processing. See `message` for details. |
| 99   | PROCESSING | The request was accepted and is being processed asynchronously. |

> Many Global Collections operations are **asynchronous**. A `code` of `1` or `99` on a create/initiate request means the request was *accepted* — the final outcome is delivered later via a webhook (see [Event Notification](https://docs.neox.vn/docs/global/global-collections/integration/event-notification.md)) or can be polled with the matching query endpoint.

## Common failure reasons

When `code = 2`, the `message` field describes the cause. Frequently seen reasons:

| Reason                            | Description                                                                                                        |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| INVALID\_TOKEN                    | The Bearer token is missing, expired, or invalid.                                                                  |
| DUPLICATE\_REQUEST\_ID            | The `requestId` was already used for a different operation.                                                        |
| VALIDATION\_ERROR                 | A request field failed validation (type, length, enum, regex).                                                     |
| RESOURCE\_NOT\_FOUND              | The referenced resource ID does not exist.                                                                         |
| SUB\_MERCHANT\_NOT\_ACTIVATED     | The sub-merchant is not yet onboarded / activated.                                                                 |
| MATERIAL\_REQUIRED                | Supplementary KYC / payer / funds-nature material must be submitted.                                               |
| INSUFFICIENT\_BALANCE             | The account balance is insufficient for the requested payout.                                                      |
| FX\_TOKEN\_EXPIRED                | The FX / payout inquiry token has expired; request a new quote.                                                    |
| INVALID\_REQUEST                  | The request is misstructured or missing information (business code `2053`).                                        |
| PAYMENT\_AMOUNT\_EXCEEDS\_BALANCE | Match request: the total of the selected collection amounts exceeds the trade order amount (business code `2053`). |
| CONTRACT\_BALANCE\_INSUFFICIENT   | Match request: the trade order amount is smaller than the collection amount (business code `2053`).                |

## Asynchronous status values

Resource-level status enums (for example virtual account, collection order, payout, FX order, sub-merchant) are documented in each endpoint's response table and in the relevant webhook document. They are distinct from the response `code` above.
