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

# Rate Limits

> Per-category quotas and the 429 response.

The API is rate limited per category. Each endpoint belongs to a category, and the limit is counted either per guild or per API key, depending on the category.

## Quotas

All windows are 60 seconds.

| Category           | Limit per minute | Counted per | Endpoints                                       |
| ------------------ | ---------------- | ----------- | ----------------------------------------------- |
| `lookup`           | 60               | Guild       | All lookup endpoints                            |
| `bindings_read`    | 100              | Guild       | `GET /bindings/list`                            |
| `bindings_write`   | 30               | Guild       | Add, update, remove, test, validate bindings    |
| `moderation_check` | 300              | API key     | Ban status, mute status, Shield check and batch |
| `moderation_read`  | 100              | Guild       | Active bans and mutes                           |
| `moderation_write` | 50               | Guild       | Roblox ban, unban, mute, unmute                 |
| `config_read`      | 100              | Guild       | Guild roles                                     |
| `roblox_activity`  | 200              | API key     | Staff permission lookups                        |
| `staff_activity`   | 200              | API key     | Action logging, game registration               |
| `staff_session`    | 100              | API key     | Session start and end                           |
| `staff_heartbeat`  | 300              | API key     | Staff heartbeat                                 |
| `server_heartbeat` | 300              | API key     | Server heartbeat                                |
| `server_poll`      | 300              | API key     | Command polling                                 |
| `server_ack`       | 100              | API key     | Command acknowledgement                         |

<Note>
  The high-frequency checks that a game runs per player join, ban and mute status and Shield, sit in `moderation_check` at 300 per minute per key, which is generous for normal play.
</Note>

## When you hit a limit

A request over the limit returns `429` with a `Retry-After` header.

```json 429 theme={null}
{
  "status": "error",
  "code": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "details": {
    "category": "moderation_write",
    "limit": 50,
    "window": 60,
    "retryAfter": 37
  }
}
```

These headers are set on a `429`:

| Header                  | Meaning                                   |
| ----------------------- | ----------------------------------------- |
| `Retry-After`           | Seconds to wait before retrying           |
| `X-RateLimit-Limit`     | The category's limit                      |
| `X-RateLimit-Remaining` | Requests left in the window, `0` on a 429 |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets     |

## Staying under the limit

* **Cache status checks.** Ban and mute checks are already cached server-side for a short window. Avoid adding `no_cache=true` unless you truly need a live read.
* **Batch where you can.** Use `POST /lookup/status` and `POST /shield/batch` instead of looping single requests.
* **Back off on 429.** Respect `Retry-After` rather than retrying immediately.