Rate limiting

A 429 rate_limited response means you're over one of the per-minute caps in Rate limits & errors — but there are several different limits in play, and which one you hit changes what to do about it.

Figure out which limit you hit

• Hitting it on /v1/search, /v1/cite, or /v1/graph/traverse? That's the plan default — 30/min on Free, 120/min on Pay As You Go.
• Hitting it specifically on /v1/reason? That endpoint has its own, much tighter limit (10/min on Pay As You Go) even though the rest of your key's traffic might be nowhere near its default limit. A busy agent that calls dike_reason per sub-step (see Agent tool-use patterns) hits this one first.
• Hitting it on /pdf/* or /survey? Those are IP-keyed, not key-keyed — if you're behind a shared NAT/proxy, other traffic on the same IP counts against you too.

Back off correctly

Limits are per minute, not a fixed token bucket you can burst into — a 429 means wait, not retry-immediately-in-a-loop. A simple fixed backoff (e.g. wait 2–3s and retry once) handles transient bursts; for sustained volume above your limit, that's a signal to batch differently (see Citation resolution workflow for why bulk /v1/cite calls need concurrency control) or move to Pay As You Go for the higher default limit.

It's not actually rate limiting

If requests are failing intermittently but you're confident you're well under the documented limits, check the error code before assuming 429 — an intermittent 503 upstream_unavailable (a downstream dependency blip) looks similar from the outside ("some requests just fail sometimes") but needs a different fix: retry-with-backoff is still right, but there's no limit to raise or traffic to reduce on your side.