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

# Error handling

> Status codes, messages, validation errors and how to recover from each.

## HTTP status codes

| Code | Description |
| - | - |
| `200` | Success. |
| `400` | Bad request: the request could not be completed (validation, out of stock, unavailable product). |
| `401` | Unauthorized: missing or invalid API key. |
| `403` | Forbidden: insufficient balance, or the IP address is not allowed. |
| `404` | Not found: unknown order, product or route. |
| `422` | Not allowed: for example insufficient allocated stock. |
| `429` | Too many requests: rate limit exceeded. |
| `500` | Internal server error. |
| `502` | Bad gateway: the upstream service is temporarily unreachable. |

## Error response format

```json theme={"dark"}
{
  "status": "error",
  "message": "Error description",
  "data": null
}
```

## Common error messages

| Message | HTTP | Description | Solution |
| - | - | - | - |
| `API key is required` | 401 | The `X-Api-Key` header is missing. | Add the header to every request. |
| `Invalid API key` | 401 | The key is wrong, was rotated, or API access is not enabled. | Check the key in the dashboard. |
| `IP address not allowed` | 403 | The request IP is not on your allow-list. | Add the IP, or remove the restriction. |
| `Insufficient balance` | 403 | Your available balance is lower than the order total. | Add funds, then retry. |
| `Insufficient allocated stock. Only N unit(s) remaining…` | 422 | Your [stock allocation](https://gateway.wasmou.net/concepts/stock.md) is smaller than the quantity. Nothing was charged. | Buy fewer units or ask for a larger allocation. |
| `Your allocated stock for this product is not currently available.` | 422 | Your allocation is paused or expired. | Contact support. |
| `Order not found` | 404 | The order does not exist or is not yours. | Check the ID. |
| `Product not found` | 404 | The product or variant does not exist. | Refresh your [catalog](https://gateway.wasmou.net/services/catalog.md). |
| `Product out of stock` | 400 | A key-based variant has no units left. | Choose another variant or wait. |
| `Validation failed` | 400 | Invalid input. | See the field errors below. |
| `Too Many Requests` | 429 | Rate limit exceeded. | Back off ([see below](#handling-rate-limits)). |
| `Upstream service unavailable` | 502 | The platform is temporarily unreachable. | Retry reads after a few seconds. |

## Validation errors

Validation errors list the problem per field:

```json theme={"dark"}
{
  "status": "error",
  "message": "Validation failed",
  "data": {
    "quantity": ["The quantity must be at least 1."],
    "player_id": ["The player id field is required."]
  }
}
```

## Handling rate limits

The limit is **60 requests per minute** per API key. When you receive `429`:

1. Wait before retrying (exponential back-off).
2. Reduce the request frequency.
3. Cache responses where you can (the [catalog](https://gateway.wasmou.net/guides/sync-catalog.md) in particular).

Back-off schedule: 1 s, 2 s, 4 s, 8 s... doubling up to a maximum (for example 60 s).

```js theme={"dark"}
async function withBackoff(fn, { retries = 6 } = {}) {
  let wait = 1000;
  for (let attempt = 0; ; attempt++) {
    const res = await fn();
    if (res.status !== 429 || attempt >= retries) return res;
    await new Promise((r) => setTimeout(r, wait));
    wait = Math.min(wait * 2, 60_000);
  }
}
```

## Refunds

If an order fails, your balance is **refunded automatically**. No action is required.

## Best practices

### 1. Always check status codes

```js theme={"dark"}
const response = await fetch(url, options);
const body = await response.json();

if (!response.ok) {
  if (response.status === 429) return retryLater();
  if (response.status === 401) throw new Error("Invalid API key");
  if (response.status === 403 && /balance/i.test(body.message)) {
    throw new Error("Please add funds to your Wasmou wallet");
  }
  throw new Error(body.message);
}
```

### 2. Validate before you submit

* Game top-ups: `POST /api/catalog/{id}/verify` checks the player ID before you pay.

### 3. Handle timeouts safely

Orders are processed asynchronously. If a request times out:

* **Do not retry immediately.** The first request may have gone through.
* Look at `GET /api/orders` to see whether the order exists.
* Save any order or transaction ID you did receive, and poll its status endpoint.

### 4. Monitor your balance

```js theme={"dark"}
const { data } = await (await fetch("https://api.wasmou.net/api/balance", {
  headers: { "X-Api-Key": apiKey },
})).json();

if (data.available_balance < orderTotal) {
  throw new Error("Top up your wallet first");
}
```

### 5. Log what you send

```js theme={"dark"}
try {
  await placeOrder(payload);
} catch (error) {
  console.error("Order failed", {
    endpoint: "/api/products/purchase/4520",
    request: payload,        // never log your API key
    error: error.message,
    timestamp: new Date().toISOString(),
  });
  throw error;
}
```

## Getting help

If an error persists:

1. Check your API key and IP allow-list.
2. Check your balance.
3. Contact [support](https://t.me/wasmou_app) with the timestamp, the request (without secrets), the message you received and the order ID if you have one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.