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

# Rate limits

> How many requests per minute the AlloMia API accepts, and how to handle a 429 response.

The API limits how many requests it accepts per minute. When you go over, it answers `429 Too Many Requests` and doesn't process the request.

## How requests are counted

* **Per client address, not per key.** The count is tied to the network address your requests come from. Two keys used from the same server share one count, and so do several systems that leave your network through the same address.
* **One count for all endpoints.** Every request from your address adds 1 to the same count, whatever the endpoint.
* **A limit per endpoint.** Each request is checked against the limit of the endpoint it calls. So after 300 requests in the window, organization requests by ID start to fail while Get call requests still succeed.
* **The window restarts with each request.** The one-minute window starts again every time a request arrives. The count only goes back to zero after a full minute with no requests from your address. A steady flow that never pauses for a minute keeps adding to the same count, even at a low rate.
* **Rejected requests count too.** A request that gets `429` still adds to the count and restarts the window.

## Limits by endpoint

| Endpoint | Limit per window (one minute) |
| - | - |
| `GET /api/organization` (List organizations) | 600 |
| `POST /api/organization` (Create organization) | 600 |
| `GET`, `PUT`, `DELETE /api/organization/{id}` | 300 |
| `PUT /api/organization/{id}/metadata` | 300 |
| `GET /api/calls` (List calls) | 600 |
| `GET /api/calls/{id}` (Get call) | 1,210 |
| `POST /api/outbound` (Create outbound call) | 600 |
| `GET /api/outbound/{id}/status` (Get outbound call status) | 600 |

The [call-completed callback](/api-reference/webhooks) goes from AlloMia to your server, so it doesn't count.

## Rate-limit headers

Responses that pass the limit check carry these headers, and so does a `429`:

| Header | Value |
| - | - |
| `X-RateLimit-Limit` | The limit of the endpoint you called. |
| `X-RateLimit-Remaining` | How many more requests this endpoint accepts before the limit, given your current count. |
| `X-RateLimit-Reset` | When the window ends if no other request arrives, as a Unix time in **milliseconds**. |
| `Retry-After` | Only on `429`. How many seconds to wait. |

## The 429 response

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791382931670

{
  "error": "Too many requests",
  "retryAfter": 60
}
```

`retryAfter` in the body is the same number of seconds as `Retry-After`.

## Handling limits

1. **On a `429`, pause everything** that calls the API from that address for at least `Retry-After` seconds. Requests sent during the pause are counted and restart the window, so they keep you blocked.
2. **Then resume gradually.** If you get another `429`, wait longer each time, for example 60, 120 and then 240 seconds, and add a little random delay so several workers don't restart together.
3. **It is safe to resend.** AlloMia didn't process a request that got `429`, so you can send it again after the pause, including `POST` requests.
4. **Watch `X-RateLimit-Remaining`.** In long jobs, such as paging through every call, pause for just over a minute before it runs out. The pause lets the count go back to zero.
5. **Ask for less.** Use `limit=50` on List calls and `limit=100` on List organizations to fetch more per request. Use the [callback](/api-reference/webhooks) instead of polling Get outbound call status.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.