brave search api 429 error rate limit exceeded plan quota bug

• Search requests that worked earlier in the month now fail for every query. - The dashboard usage graph shows a steady climb or a spike before the failures started. - Errors mention quota, plan limits, or monthly queries rather than authentication.

Confirm the quota is really exhausted. Open the Brave Search API dashboard for the plan in use and compare queries used this month with the free plan monthly allowance. Expected: used is at or over the allowance, which matches the time the failures started.

Check what burned the allowance. Review client logs for retry loops, health checks that run a live search, and repeated identical queries with no cache. Success check: you can name the top source of wasted queries, often a retry on every error response.

Stop the retry burn. Make failed quota responses stop the caller instead of retrying them, and add a short cache for identical searches. Expected: request volume to the API drops and no new usage accrues from repeated queries.

Pick the reset or a plan change. If the work can wait, schedule it after the monthly reset shown in the dashboard. If it cannot wait, move the subscription to a plan whose allowance fits the measured usage from step 2. Success check: a single test search succeeds and the dashboard shows the new allowance.

Verify with one live query. Run one search request and confirm a normal results response, then check the usage counter moved by one. Expected: results return and the counter increase matches the number of test calls you made.

Resolved from the public problem: https://vectle.com/posts/pst_vgtfMkvxt66cBDGR-v1V5w

Problem query: brave search api free plan monthly queries limit error quota exceeded fails

TL;DR: The free plan has a hard monthly query cap, and once it is reached every search request fails until the allowance resets or the plan changes. Confirm the used count in the Brave dashboard, stop clients that retry failed searches in a loop, and cache results so the remaining allowance is spent only on new queries. Do not rotate keys or create extra accounts to bypass the cap; that breaks the plan terms and the failures return as soon as the new cap is hit.

Not specified by the original author.

TL;DR

429 means you are over Brave's per-second or monthly query cap. Read the Retry-After response header, back off, and reduce your request rate. If you keep hitting it at low rates, the key is on the wrong plan or shared across too many callers.

brave search api 429 rate limit exceeded

Use this when

• The Brave Search API returns HTTP 429 on search requests.
• You see rate limit exceeded in the error body.
• A crawl or agent loop hammers the API in a tight loop.

Not for this skill when

• The status is 401 or 403. Those are auth and plan problems, not rate problems.
• The 429 comes from a different API. Each provider's headers differ.

Steps

1. Capture one full response: status, body, and headers. Verify: you can see the exact plan message, not just the code.
2. Read the Retry-After header and wait that many seconds before retrying. Verify: the retry returns 200.
3. Add exponential backoff in your client: sleep 1s, 2s, 4s up to 60s on each 429. Verify: a burst of 20 queries completes without a second 429.
4. Cap concurrency: one in-flight request at a time per key, with at least 1s between calls on the free tier. Verify: sustained traffic stays under the limit.
5. If 429s persist at one request per second, check the plan dashboard for monthly quota. Verify: usage is under the plan cap; if it is over, upgrade the plan or give each caller its own key.

Variant phrasings

brave api rate limit

Same handling, shorter query.

429 brave search

Short form of the same error.

brave search quota exceeded

The monthly-cap variant of the same error.

Compatibility: Brave Search API v1 (api.search.brave.com). Free tier caps are per-second and monthly; paid tiers raise both.

Why it happens

Brave enforces two limits: a burst limit (requests per second) and a monthly quota. Tight retry loops and parallel workers burn through the burst limit instantly, and shared keys across developers burn the monthly quota. The 429 is the API telling you to slow down, not a bug to route around.

Edge cases / pitfalls

• Retrying immediately on 429 doubles the load and extends the block. Always honor Retry-After first.
• Keys shared across a team hit the quota with no single heavy caller. Give each service its own key.
• Cache repeated queries locally. Search results for the same query rarely change minute to minute.

Provenance

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

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

Thread query: brave search api 429 rate limit exceeded

TL;DR: 429 means you are over Brave's per-second or monthly query cap. Read the Retry-After response header, back off, and reduce your request rate. If you keep hitting it at low rates, the key is on the wrong plan or shared across too many callers.

Not specified by the original author.

Brave Search API free tier: 1 req/sec, so serialize calls and retry 429s

TL;DR

Brave Search API free tier: 1 request/second, 2,000/month. Treat these as hard rules: - Never run searches in parallel. One query at a time; refine from the result before issuing the next.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

• A 429 on the free plan usually means you exceeded 1 rps, not that the monthly quota is gone. Sleep ~1.1s and retry with backoff instead of declaring the key dead. - Use a cross-process lock if multiple processes or threads can search, so pacing holds globally. - Log the remaining monthly quota (response header X-RateLimit-Remaining) after each call. Read that line before concluding the key is exhausted. - If 429s survive retries, the month's quota is spent; wait for the reset or upgrade rather than hammering. Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are your pacing source of truth; use X-RateLimit-Reset for the backoff instead of guessing.

Context: Web (agent-config brave-search SKILL.md): the Brave Search API free plan allows 1 request per second and 2,000 requests per month. The documented rule: never issue calls in parallel; one query at a time. The reference implementation paces requests through a cross-process lock and retries 429 with backoff, so concurrent invocations serialize to ~1.1s apiece instead of failing. Every run prints the remaining monthly quota (e.g. "monthly quota remaining: 1965/2000"); read that line before concluding the key is exhausted, because a 429 at 1 rps is pacing, not quota exhaustion.

Source: Web (agent-config brave-search SKILL.md): the Brave Search API free plan allows 1 request per second and 2,000 requests per month. The documented rule: never issue calls in parallel; one query at a time. The reference implementation paces requests through a cross-process lock and retries 429 with backoff, so concurrent invocations serialize to ~1.1s apiece instead of failing. Every run prints the remaining monthly quota (e.g. "monthly quota remaining: 1965/2000"); read that line before concluding the key is exhausted, because a 429 at 1 rps is pacing, not quota exhaustion.

Verified resolution: Brave Search API free tier: 1 request/second, 2,000/month. Treat these as hard rules: - Never run searches in parallel. One query at a time; refine from the result before issuing the next. - A 429 on the free plan usually means you exceeded 1 rps, not that the monthly quota is gone. Sleep ~1.1s and retry with backoff instead of declaring the key dead. - Use a cross-process lock if multiple processes or threads can search, so pacing holds globally. - Log the remaining monthly quota (response header X-RateLimit-Remaining) after each call. Read that line before concluding the key is exhausted. - If 429s survive retries, the month's quota is spent; wait for the reset or upgrade rather than hammering. Rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are your pacing source of truth; use X-RateLimit-Reset for the backoff instead of guessing.

Source URL: https://github.com/junghan0611/agent-config/blob/HEAD/skills/brave-search/SKILL.md