# Rate limits

Part of the InboxWA API reference: https://inboxwa.online/docs/api . Full reference as one document: https://inboxwa.online/docs/api.md . OpenAPI: https://inboxwa.online/openapi.json

Each key is limited per minute. The default is 600 requests per minute per key, and a key can be given its own limit from 10 to 100,000. Some long-standing integrations are exempt.

> **Sending is not throttled by the default** Sending messages is metered by your credits and by WhatsApp’s own limits, not by request rate. `POST /api/send-message` and `POST /api/bulk-send` are therefore not held to the default limit, and are not counted against it. A limit you set on a key yourself is a deliberate choice and applies to every call, including sends.

Every response from a limited key carries the current state:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit` | Requests allowed per minute for this key. |
| `X-RateLimit-Remaining` | Requests left in the current window. |
| `X-RateLimit-Reset` | Seconds until the window rolls. |
| `Retry-After` | On a 429 only: seconds to wait before retrying. |

**429 Too Many Requests**

```json
{
  "error": "rate_limited",
  "message": "This key is limited to 600 requests per minute. Retry after 12s.",
  "retry_after_seconds": 12
}
```

- Back off for `Retry-After` seconds, then retry. Do not retry in a tight loop.
- Do not poll the same endpoint faster than every 30 seconds. For "tell me when something happens", use webhooks.
- Prefer one list call with filters over many single-item calls.

## Two limits, two response shapes

A key is held to its own limit, and all API traffic from one IP address is also held to a platform-wide ceiling. Both answer 429, but they answer differently. Whichever you meet, back off for `Retry-After` seconds.

|  | Per-key limit | Per-IP ceiling |
| --- | --- | --- |
| Limit | 600 a minute by default, or the key’s own | 1,000 a minute per IP address |
| Not applied to | Sending (`/api/send-message`, `/api/bulk-send`) on a key with no limit of its own | Sending (`/api/send-message`, `/api/bulk-send`) |
| Body | `{"error":"rate_limited","message":"...","retry_after_seconds":12}` | `{"error":"Too many requests, please try again later."}` |
| Headers | `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After` | `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`, `Retry-After` |

A per-key limit above 1,000 a minute only helps when calls come from more than one IP address, because the ceiling applies first.