> 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](/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.      |

## 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.