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

# Rate limits

> Per-key request limits, the headers that report them, and how to back off.

API requests are rate limited per API key, in a rolling one-minute window. Limits vary by plan tier.

## Reading your limit

Every response carries the current state, so you never have to guess:

| Header                  | Meaning                             |
| ----------------------- | ----------------------------------- |
| `X-RateLimit-Limit`     | Requests allowed in the window      |
| `X-RateLimit-Remaining` | Requests left in the current window |
| `X-RateLimit-Reset`     | Seconds until the window resets     |

When you exceed the limit you get `429` with a `Retry-After` header giving the seconds to wait.

```json theme={null}
{
  "success": false,
  "message": "Rate limit exceeded. 60 requests per minute allowed on starter plan."
}
```

<Note>
  Treat `X-RateLimit-Limit` as authoritative for your account rather than hard-coding a number. It reflects the tier your workspace is actually on.
</Note>

## Limits are per key

The window is tracked against the API key, not your workspace or your IP. Two integrations with separate keys get separate budgets — another reason to issue one key per integration rather than sharing one. See [Authentication](/api-reference/authentication).

## Staying under

<Steps>
  <Step title="Read the headers, don't count locally">
    Check `X-RateLimit-Remaining` and slow down as it approaches zero. Local counters drift, especially across multiple workers.
  </Step>

  <Step title="Back off exponentially on 429">
    Honor `Retry-After`, then double the wait on repeat failures. Add jitter so parallel workers don't all retry at the same instant.
  </Step>

  <Step title="Page sensibly rather than polling hard">
    Request a page at a time and work through it. Repeatedly polling a list endpoint for changes is the most common way to hit the limit.
  </Step>

  <Step title="Use webhooks instead of polling">
    If you're polling to detect new calls or messages, stop — subscribe instead. It's faster and costs no requests. See [Webhooks](/api-reference/webhooks).
  </Step>
</Steps>

<Tip>
  Almost every rate-limit problem is a polling loop. One `call.ended` webhook replaces a job that checks for new calls every ten seconds, and it delivers within seconds instead of on the next poll.
</Tip>

## Separate from plan limits

Rate limits cap how fast you can call the API. They're distinct from your plan's **call allowance**, which caps how many calls your workspace makes and receives in a billing period.

A `429` on call creation may be either — the `message` tells you which. See [Usage & overages](/account/usage-and-overages).

## Need a higher limit?

If a legitimate workload doesn't fit, contact [info@recepta.ai](mailto:info@recepta.ai) with your workspace name, the integration, and the request pattern. It's worth checking first that webhooks and pagination wouldn't solve it more cheaply.