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

# Rate limits

> Per-route rate limits, response headers, and backoff guidance.

Public API v1 enforces per-route rate limits keyed by API key (falling back to client IP when no key is present).

## Limits by endpoint class

| Endpoint class | Routes                                                              | Limit                 |
| -------------- | ------------------------------------------------------------------- | --------------------- |
| **List**       | `GET /tickets`, `GET /views`                                        | 60 requests / minute  |
| **Detail**     | `GET /tickets/:ticketNumber`, `GET /tickets/:ticketNumber/messages` | 120 requests / minute |

`GET /health` uses the detail tier.

List and detail limits are **independent** — exhausting the list budget does not block detail requests.

## Response headers

Every response includes rate limit headers:

| Header                  | Meaning                                  |
| ----------------------- | ---------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests allowed in the window   |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset`     | Unix timestamp when the window resets    |

When you exceed the limit, the API returns **`429`** with code `RATE_LIMIT_EXCEEDED` and a `Retry-After` header (seconds to wait). The error envelope may also include `retry_after`.

```json theme={null}
{
  "success": false,
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded.",
  "request_id": "req_...",
  "retry_after": 42
}
```

## Best practices

* **Backoff on 429** — sleep for `Retry-After` seconds (or exponential backoff with jitter) before retrying.
* **Avoid tight polling loops** — use reasonable intervals for agent tools; combine [cursor pagination](/api/pagination) with backoff instead of hammering list endpoints.
* **Cache view metadata** — `GET /views` changes infrequently; cache view `id` → name/filter mapping in your integration.
* **Batch sensibly** — fetch message threads only for tickets you need, not every row in a list response.

## Legacy `/public/*` limits

Deprecated legacy endpoints use different limits (30–300 requests / minute depending on endpoint). See the [legacy OpenAPI reference](https://api.armin.cx/docs) if you still call `/public/*` during migration.