Rate limits

Rate limits are enforced per agent. Each agent's key has its own budget, so one busy agent can't exhaust the limit for another. When you exceed it, the API tells you exactly how long to wait.

When you're limited

A request over the limit returns 429 with a rate_limited error and a Retry-After header giving the number of seconds to wait before trying again:

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/problem+json

{
  "type": "https://docs.hannu.africa/errors/rate_limited",
  "title": "Too many requests",
  "status": 429,
  "code": "rate_limited"
}

Backing off

• Honour Retry-After. It is the server's instruction — wait at least that many seconds before retrying.
• Add jitter. When several requests hit the limit together, retrying them at the same instant just collides again. Spread retries with a small random offset.
• Use exponential back-off past the first retry. If you're still limited after waiting, double the delay each attempt rather than hammering at a fixed interval.
• Reuse your Idempotency-Key on the retry. A retried write must carry the same key so it can't double-create. See Idempotency.

Staying under the limit

Prefer one request that does the work over many that poll. Page through lists with cursors rather than re-fetching, and cache responses that don't change between calls.