# Rate Limits

Prontuno applies request limits to protect API availability. The limit is shared by all authenticated public API operations and all API keys belonging to the same team.

## Rate-limit headers

When rate limiting is active, authenticated responses include:

- Header | Meaning
- `RateLimit-Limit` | The maximum number of requests available to the team in the current window.
- `RateLimit-Remaining` | The number of requests remaining in the current window.
- `RateLimit-Reset` | The number of seconds until the current window resets.

Read these headers dynamically instead of hard-coding a plan limit. Limits can vary by team and may change over time.

## Rate-limit response

After the allowance is exhausted, the API returns HTTP `429 Too Many Requests`. The response includes `Retry-After`, expressed in seconds:

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 12
Content-Type: application/json
```

```
{
    "error": {
        "code": "rate_limit_exceeded",
        "message": "Rate limit exceeded",
        "retryable": true,
        "suggested_action": "retry_later",
        "retry_after_seconds": 12
    }
}
```

## Handle limits safely

- Stop sending requests when `RateLimit-Remaining` reaches zero.
- On `429`, wait at least `Retry-After` seconds.
- Add random jitter before retrying so multiple workers do not resume at once.
- Coordinate concurrency across every worker and service using keys for the same team.
- Queue traffic in your application instead of dropping requests during a busy period.
- Use an `Idempotency-Key` when retrying email sends.

A second API key for the same team does not increase throughput because both keys use the same team-level allowance.

## Batching and request limits

A batch-send call counts as one API request, while the batch can contain up to 1,000 email items. Batching can reduce request pressure, but it does not bypass recipient credit checks, payload-size limits, or per-item validation. The entire batch JSON body must remain within 15 MB.