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

# rate_limited

> Too many requests for this key, or sends faster than the sender's sending rate (pacing).

HTTP 429. Too many requests for this key, or sends faster than the sender's sending rate (pacing).

## What it means

Two limits answer with this type:

* **The per-key request limit.** Every answer carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`; over the limit, any request is refused. The Testing endpoints (`/v0/test/...`, simulated contacts) have a lower limit of their own, 120 requests a minute per key, and their answers' headers show it.
* **The sender's sending rate (pacing).** The send gate lets each sender send only so many messages a second, whichever key or conversation they come from. Over it, a send is refused and `error.sender` names the sender.

Both carry a `Retry-After` header and `error.retry_after` in seconds.

## Why it happens

* Polling `GET /v0/events` or `GET /v0/conversations` in a tight loop, or a simulated conversation's transcript (`GET /v0/test/conversations/{conversation_id}/transcript`).
* Sending many messages from one sender at once, for example a reply split into many short bubbles, or a burst of starts.
* Asking for many sandbox keys (`POST /v0/sandbox/keys`) or device sign-ins from one address or network. Keep the key you got and reuse it; a person can sign in to lift its allowance instead.
* Polling `POST /v0/device/token` faster than its `interval`.

## How to fix it

Wait `Retry-After` seconds (also `error.retry_after`) and retry with the same `Idempotency-Key`, so a send that did go through is not sent twice. Receive events by webhook or `GET /v0/stream` instead of polling, and send long answers as fewer, longer messages. The TypeScript SDK does the wait and the retry for you.

```ts
const res = await fetch(url, init);
if (res.status === 429) await sleep(Number(res.headers.get("Retry-After")) * 1000);
// then send the same request again with the same Idempotency-Key header
```

Every error also carries `hint`, one sentence specific to your request, and
`doc_url`, this page. Coding agents connected to Flow's MCP server
(`https://api.flow.engineer/mcp`) can call `explain_error` with the type to read this page.