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

# Troubleshooting: XPayLabs Gateway Error Solutions

> Diagnose and fix common XPayLabs issues — HMAC signature failures, blockchain scanner problems, webhook delivery errors, Docker deployment issues, and rate limiting.

Diagnose and resolve common problems with your XPayLabs gateway deployment and API integration. This guide covers HMAC signature errors, blockchain scanner issues, webhook delivery failures, and Docker deployment problems.

***

## API Issues

### Why am I getting 401 sign verification failed?

The HMAC-SHA256 signature does not match what the gateway computed.

**Checklist:**

1. **JSON serialization** — Ensure the `data` object is serialized as **compact JSON** (no spaces, no newlines). `JSON.stringify(obj)` in JavaScript produces the correct format by default.

2. **Data content** — The `sign` is computed over only the `data` field, not the full request envelope. The `sign`, `timestamp`, and `nonce` fields are excluded.

3. **Token mismatch** — Confirm the `MERCHANT_TOKEN` used to compute the signature matches the token configured in the gateway.

4. **Character encoding** — Ensure the token and JSON string are UTF-8 encoded.

5. **Test your signature** — Compute the signature for a known payload and compare:

```javascript theme={null}
const crypto = require("crypto");
const token = "your-merchant-token";
const data = { amount: "100.00", symbol: "USDT", chain: "TRON" };
const sign = crypto
  .createHmac("sha256", token)
  .update(JSON.stringify(data), "utf8")
  .digest("hex");
console.log(sign); // Should match what gateway expects
```

### Why am I getting 400 validation errors?

| Message                               | Likely Cause                                                 |
| ------------------------------------- | ------------------------------------------------------------ |
| `"The amount cannot be left blank."`  | `amount` is `null`, `undefined`, or not a valid number       |
| `"The symbol cannot be left blank."`  | `symbol` is missing or an empty string                       |
| `"The chain cannot be left blank."`   | `chain` is missing or not a valid chain value                |
| `"ReceiveAddress error"`              | The payout address format does not match the specified chain |
| `"The uid cannot be left blank."`     | Your merchant account is V2 and requires `uid`               |
| `"The orderId cannot be left blank."` | Your merchant account is V3 and requires `orderId`           |

***

## Blockchain Scanner Issues

## Why are blockchain payments not detected?

If the scanner is not detecting incoming payments:

1. **Check scanner logs:** `docker logs <scanner-container-name>`
2. **Verify RPC endpoints:** Ensure the configured RPC URL is accessible from the gateway server.
3. **Check block height:** The scanner syncs from the last processed block. If the gateway was recently deployed, it may need time to catch up.
4. **Confirm token configuration:** Verify the token contract address is correctly configured for the chain.
5. **Check blockchain explorer:** Confirm the transaction actually exists on-chain at the expected address.

### Why is the scanner slow?

* **RPC rate limits:** Public RPC endpoints may throttle high-frequency requests. Consider using dedicated RPC endpoints.
* **Block time:** Different chains have different block times. TRON produces blocks every 3 seconds, Ethereum every 12 seconds.
* **Confirmation requirements:** Configure the required number of block confirmations per chain in the gateway settings.

***

## Webhook Problems

## Why am I not receiving webhooks?

1. **Verify callback URL:** Check the `callback-url` in your gateway configuration.
2. **Network accessibility:** The gateway must be able to reach your callback URL. If testing locally, use a tunneling tool like ngrok.
3. **Check gateway logs:** `docker compose logs xpay-user` to see webhook delivery attempts.
4. **Check your endpoint logs:** Ensure your server is listening on the correct path and returning HTTP 200.

### Why is webhook signature verification failing?

1. **Raw data vs. full payload:** Verify the signature over the `data` field only, not the full `NotifyPayload`.
2. **Webhook secret mismatch:** Confirm the `webhook-secret` used for verification matches what is configured in the gateway.
3. **JSON format:** The `data` field must be serialized as compact JSON for verification.

***

## Deployment Issues

## Why are Docker containers not starting?

```bash theme={null}
# Check container status
docker compose ps

# View logs for a specific service
docker compose logs xpay-user
docker compose logs xpay-tron
```

Common causes:

* Port `180` already in use
* Insufficient disk space
* Missing environment variables in configuration

### Why is the gateway not responding?

1. **Verify container is running:** `docker compose ps` should show `Up` status.
2. **Check port binding:** `docker compose port gateway 180`
3. **Test locally:** `curl http://localhost:180/v1/symbol/supportSymbols`
4. **Check firewall:** Ensure port 180 is open in your server firewall.

***

## Rate Limiting

If you receive `429 Too Many Requests`:

| Endpoint                       | Default Limit          |
| ------------------------------ | ---------------------- |
| `POST /order/createCollection` | 100 req / 10s per IP   |
| `POST /order/createPayout`     | 100 req / 10s per IP   |
| `GET /order/pay`               | 2 req / 1s per orderId |
| `GET /order/getOrderStatus`    | 2 req / 1s per orderId |

Implement exponential backoff in your integration:

```javascript theme={null}
async function fetchWithRetry(url, options, retries = 5) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);
    if (response.status !== 429) return response;
    const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
    await new Promise(r => setTimeout(r, delay));
  }
  throw new Error("Max retries exceeded");
}
```

***

## Getting Help

If you cannot resolve your issue:

1. Check the container logs for error messages.
2. Review the [FAQ](/faq) for common questions.
3. Open a GitHub issue at [github.com/xpaylabs/gateway](https://github.com/xpaylabs/gateway).
4. For commercial support, contact [support@xpaylabs.com](mailto:support@xpaylabs.com).

When reporting an issue, include:

* Gateway version and deployment method
* Relevant configuration (redact secrets)
* Complete error messages and logs
* Steps to reproduce