> For the complete documentation index, see [llms.txt](https://docs.butlr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.butlr.io/data-center/errors-and-limits.md).

# Errors and limits

## HTTP status codes

| Status        | Meaning                                                               | Client action                            |
| ------------- | --------------------------------------------------------------------- | ---------------------------------------- |
| `400`         | Invalid parameter, body, time window, or GraphQL input.               | Fix the request; do not retry unchanged. |
| `401`         | Missing, unknown, expired, or revoked token.                          | Replace or rotate the credential.        |
| `403`         | Route or mutation denied, or resource outside the token organization. | Stop; do not retry with other IDs.       |
| `404`         | Resource not found inside the authorized surface.                     | Refresh inventory.                       |
| `429`         | Per-token or source-IP limit reached.                                 | Honor `Retry-After` and back off.        |
| `502` / `503` | Required archive, database, or token store unavailable.               | Retry with bounded exponential backoff.  |

## Defensive limits

* Per token: 10 requests per second, burst 20.
* Per source IP: 30 requests per second, burst 60.
* Request body: 1 MiB maximum for API-token requests.
* GraphQL complexity: 250 maximum.
* Raw frames: maximum 5,000 returned per request.

Operational limits can be reduced. Clients should use low-volume sequential requests, add jitter to retries, and avoid retrying `401` or `403` indefinitely.

## Read-only enforcement

GraphQL mutations and all token-management writes are rejected for an Organization API Token. This remains true even if the token was issued by an administrator.
