> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XPayLabs API Errors: Codes, Causes, and Solutions

> XPayLabs returns structured error responses with HTTP status codes and validation error messages. Handle blockchain payment errors gracefully with our troubleshooting guide.

XPayLabs returns errors using a standard `R<T>` envelope with an HTTP-compatible `code` and a human-readable `msg`. Unlike traditional payment processors, XPayLabs errors are primarily validation and authentication errors — since blockchain transactions are final, there are no "card declined" or "insufficient funds" errors at the API level (those are blockchain-level issues).

## What is the error response format?

```json theme={null}
{
  "code": 400,
  "msg": "The amount cannot be left blank.",
  "data": null
}
```

| Field  | Type    | Description                      |
| ------ | ------- | -------------------------------- |
| `code` | integer | HTTP-compatible status code      |
| `msg`  | string  | Human-readable error description |
| `data` | null    | Always `null` in error responses |

## Status Codes

| Code  | Meaning           | Typical Cause                               |
| ----- | ----------------- | ------------------------------------------- |
| `400` | Bad Request       | Missing or invalid parameters               |
| `401` | Unauthorized      | Invalid HMAC signature or expired timestamp |
| `422` | Unprocessable     | Invalid address format for chain            |
| `429` | Too Many Requests | Rate limit exceeded                         |
| `500` | Internal Error    | Unexpected gateway error                    |

## Common Validation Errors

### Signature Errors (`401`)

| Message                                 | Cause                                       |
| --------------------------------------- | ------------------------------------------- |
| `"The sign cannot be left blank."`      | `sign` field is missing from the request    |
| `"Sign verification failed"`            | HMAC signature doesn't match computed value |
| `"The timestamp cannot be left blank."` | `timestamp` is missing                      |
| `"The nonce cannot be left blank."`     | `nonce` is missing                          |

### Order Errors (`400`)

| Message                                      | Cause                                             |
| -------------------------------------------- | ------------------------------------------------- |
| `"The amount cannot be left blank."`         | Amount is missing or null                         |
| `"The symbol cannot be left blank."`         | Token symbol is missing                           |
| `"The chain cannot be left blank."`          | Blockchain network is missing                     |
| `"The receiveAddress cannot be left blank."` | Payout destination address is missing             |
| `"ReceiveAddress error"`                     | Address format is invalid for the specified chain |
| `"The orderId cannot be left blank."`        | Required for V3 merchants                         |
| `"The uid cannot be left blank."`            | Required for V2 merchants                         |
| `"The uid cannot be zero."`                  | uid is set to `"0"`                               |

## Handling Errors in Your Integration

```javascript theme={null}
async function createCollection(payload) {
  const response = await fetch("http://your-gateway:180/v1/order/createCollection", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const result = await response.json();

  if (result.code !== 200) {
    switch (result.code) {
      case 401:
        // Signature issue — recompute sign and retry
        console.error("Auth error:", result.msg);
        break;
      case 400:
        // Validation error — fix request parameters
        console.error("Validation error:", result.msg);
        break;
      case 429:
        // Rate limited — back off and retry
        await sleep(1000);
        return createCollection(payload);
      default:
        console.error("Unexpected error:", result.msg);
    }
    return null;
  }

  return result.data;
}
```

## Rate Limiting

XPayLabs enforces configurable rate limits per endpoint. Exceeding the limit returns a `429` response.

Default limits:

| Endpoint                  | Limit                  |
| ------------------------- | ---------------------- |
| `/order/createCollection` | 100 req / 10s per IP   |
| `/order/createPayout`     | 100 req / 10s per IP   |
| `/order/status/{orderId}` | 1000 req / 10s         |
| `/order/pay`              | 2 req / 1s per orderId |
| `/order/getOrderStatus`   | 2 req / 1s per orderId |
| `/symbol/supportSymbols`  | 50 req / 10s           |