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

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.