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

# Error Codes

The error format is described in [Protocol Overview → Errors](/documentation/eng/concepts/protocol.md#formaty-otvetov). Below is the full list of codes that may appear in the `message` field.

## General Errors

| HTTP | Code                                     | Description                                                       |
| ---- | ---------------------------------------- | ----------------------------------------------------------------- |
| 400  | INVALID\_MERCHANT\_ID                    | Invalid or missing merchant identifier                            |
| 400  | Invalid amount limits (min–max CURRENCY) | Amount is outside the general method/currency limits              |
| 401  | INVALID\_API\_KEY                        | Invalid API key or incorrect signature                            |
| 403  | DISABLED                                 | Merchant is disabled or payment method is temporarily unavailable |
| 429  | TOO\_MANY\_REQUESTS                      | Request rate limit exceeded                                       |
| 500  | Internal server error                    | Internal server error                                             |

## Order Errors

| HTTP | Code                             | Description                                             |
| ---- | -------------------------------- | ------------------------------------------------------- |
| 404  | ORDER\_NOT\_FOUND                | Order not found by the specified identifier             |
| 404  | MERCHANT\_NOT\_FOUND             | No merchant found with the specified `merchant_id`      |
| 409  | ORDER\_ALREADY\_EXISTS           | An order with this `order_id` already exists            |
| 409  | ORDER\_AMOUNT\_BELOW\_MIN\_LIMIT | Order amount is below the merchant's minimum            |
| 409  | ORDER\_AMOUNT\_ABOVE\_MAX\_LIMIT | Order amount is above the merchant's maximum            |
| 409  | REQUISITES\_NOT\_FOUND           | Failed to retrieve payment details for the order        |
| 400  | CURRENCY\_MISMATCH               | Request currency does not match the merchant's currency |
| 403  | USDT\_CONVERSION\_NOT\_ALLOWED   | USDT conversion is not permitted for this merchant      |

## Payout Errors

| HTTP | Code                               | Description                                                   |
| ---- | ---------------------------------- | ------------------------------------------------------------- |
| 400  | INVALID\_PAYOUT\_DETAILS           | Invalid payout data (holderAccount, holderName, methodName)   |
| 400  | INVALID\_HOLDER\_ACCOUNT           | Invalid payment detail format: 16 digits for card, 11 for SBP |
| 400  | PAYOUT\_UNSUPPORTED\_TYPE          | The specified `type` does not support payouts                 |
| 403  | PAYOUT\_NOT\_ALLOWED               | Payouts are disabled for this merchant                        |
| 409  | INSUFFICIENT\_BALANCE\_FOR\_PAYOUT | Insufficient balance to cover the payout (including fees)     |
| 409  | PAYOUT\_MIN\_AMOUNT\_VIOLATION     | Payout amount is below the minimum allowed                    |

{% hint style="info" %}
On a `REQUISITES_NOT_FOUND` error, it is recommended to retry the request after 5–10 seconds — payment details may become available.
{% endhint %}