## TL;DR
Treat 429 as a slow-down signal, not an outage: back off with jittered exponential delays and cut request volume until your minute quota recovers. Then check your Tavily dashboard for per-minute usage vs plan limit; if you are on the free tier and doing bulk work, upgrade or queue the work.

```text
tavily 429 too many requests
```

## Use this when
- Tavily /search, /extract, /crawl, or /map returns HTTP 429
- Burst scripts that fire dozens of calls per second start failing mid-run
- You need a retry wrapper for Tavily calls in an agent or pipeline

## Not for this skill when
- Tavily returns 401/403 (key problem, not rate problem)
- Results come back empty or irrelevant (query quality, not quota)
- Another search API (Serper, Exa, Brave) is returning the 429

## Steps
1. Read the response headers for rate-limit info: Retry-After, X-RateLimit-Remaining, X-RateLimit-Reset. Expected: you know whether the window is seconds or minutes.
2. Wrap calls in retry with exponential backoff plus jitter: 1s, 2s, 4s, 8s, capped at 60s, max 5 attempts. Expected: transient 429s clear within the window instead of hammering through it.
3. Add client-side pacing: a token bucket or a simple 1-2 calls per second limiter for bursts, especially around /extract on long pages. Expected: sustained throughput stays under the plan's per-minute ceiling.
4. Check the Tavily dashboard usage page for the current period's request counts and your plan's limits. Expected: you can tell quota exhaustion apart from a burst spike.
5. If the dashboard shows you at the plan ceiling, either upgrade the plan or serialize the backlog into a queue that drains at the allowed rate. Expected: zero 429s on the next full run.

## Variant phrasings
### Tavily search API rate limited
Same fix path: backoff plus pacing, then quota triage on the dashboard.
### tavily too many requests extract endpoint
The extract endpoint is the heaviest consumer; serialize extract calls and keep search concurrency low.

## Tool/version compatibility
Applies to Tavily's REST API (api.tavily.com) and the tavily-python SDK, which exposes the raw status via its exception object. Header names are as of 2026; check current docs if a header is missing.

## Why it happens
Tavily enforces per-minute request limits per plan tier. Bulk pipelines that parallelize search plus extract calls can exceed the window in seconds. Retrying immediately makes it worse because the burst extends the over-limit window, which is why jittered backoff plus client-side pacing is the correct response rather than faster retries.

## Edge cases / pitfalls
- Never retry 429s with no delay; immediate retries are the classic way to turn a 10-second pause into a locked-out minute.
- Separate quotas can apply per endpoint; a green /search does not mean /extract is green.
- /crawl jobs count each fetched page; one crawl job can burn a large chunk of quota.
- This skill covers legitimate pacing only: do not rotate keys or create extra accounts to evade limits.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MQam9IpGukQt43wU_VzeDg