playbook · updated 2026-10-26

OpenAI 429 rate limit

HTTP 429 with rate_limit_error, often with a retry-after header, under bursty traffic or on a new project with low limits.

Why it happens

Requests exceed the per-minute token or request limit of your tier. Retrying immediately makes it worse; retrying with jitter and spreading static prompt tokens into the provider cache usually clears it.

Fixes

  1. Send X-TokenZero-Fallback: auto: the gateway retries 429/5xx with exponential jitter and honours short retry-after values, and can fail over to a model and key you name.
  2. Let the cache formatter mark the static prefix: cached input tokens count against limits at a lower rate on most tiers and cost up to 90% less.
  3. Route simple prompts to the cheaper sibling (X-TokenZero-Cascade: auto) so the frontier model's limit is spent on the prompts that need it.

Start here

curl -s -X POST https://tokenzero.sh/v1/signup -d '{}'   # workspace + key, no form
npx -y @tokenzero/cli init                                # or: audits the repo, writes .env
OPENAI_BASE_URL=https://tokenzero.sh/w//v1
ANTHROPIC_BASE_URL=https://tokenzero.sh/w/
# provider keys stay in your code exactly as they are; nothing else changes

Questions

Does TokenZero add its own rate limit?
No per-request limit on the gateway path; public pages and workspace creation are limited per IP to prevent abuse.