This 429 means the request or token rate exceeded an assigned API limiter. OpenAI rate capacity is Varies by model and usage tier, so inspect the error code and response headers before retrying.
Why does this error happen?
- A loop or concurrent workers sent requests too quickly.
- Token throughput was exhausted even though request count looked safe.
- Other users or projects consumed shared organization capacity.
How do you diagnose it?
- Inspect error.code so you do not confuse a temporary rate error with credit_balance_exhausted or a spend/usage limit error.
- Read Retry-After and the x-ratelimit-* limit, remaining, and reset headers.
- Compare aggregate requests and tokens across every worker using the organization or project.
const delay = response.headers.get("retry-after");
// Treat Retry-After as the minimum wait for eligible temporary 429s.
// Bound attempts and add jitter when implementing your own client.How do you fix it?
- Honor Retry-After when present; otherwise use bounded exponential backoff with jitter.
- Queue or smooth concurrent work and remove redundant calls.
- Do not retry credit, billing, spend, or usage-limit errors until the underlying account condition changes.
How do you prevent it from recurring?
Turn the confirmed cause of 429 — Rate limit reached for requests into an observable boundary for OpenAI API. Track the relevant request count, token volume, payload size, execution time, connection pressure, billing state, or upstream health before it reaches the documented failure condition. Preserve the platform request ID and timestamp so future incidents can be correlated without logging sensitive payloads.
Test the fix under representative concurrency and failure injection, not only with one successful request. Alert on remaining headroom and repeated retries, and keep the linked limit page and official error source with the runbook so responders can distinguish a configuration problem from temporary service pressure or account state.