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

# Rate limits

> Request limits and response headers

The API uses per-second rate limits. Limits are applied per API key.

## Default limits

| Operation                                 | Limit              |
| ----------------------------------------- | ------------------ |
| Read requests (GET)                       | 20 requests/second |
| Write requests (POST, PUT, PATCH, DELETE) | 5 requests/second  |

## Rate limit headers

Every response includes rate limit information:

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

## Exceeding the limit

When you exceed the rate limit, the API returns `429 Too Many Requests`:

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the rate limit of 20 requests per second.",
    "retryable": true,
    "request_id": "req_a1b2c3d4e5f6",
    "retry_after_seconds": 1
  }
}
```

The response also includes a `Retry-After` header with the number of seconds to wait.

## Best practices

1. **Respect `Retry-After`** — wait the indicated time before retrying
2. **Use exponential backoff** — if retries keep failing, increase the wait time
3. **Cache responses** — store results locally to avoid redundant requests
4. **Use `last_activity_since`** — for sync workflows, only fetch conversations with new activity instead of re-fetching everything
5. **Use `total_count`** — to answer "how many?" questions without paginating through all results