OpenAI — rate limit exceeded with 429 and retry-after
OpenAI returns 429 Too Many Requests because the request rate or token usage exceeds the account tier limit, with a retry-after header indicating when to retry.
Symptoms
- error: 429 Rate limit reached for requests
- The error includes a retry-after or rate limit reset header
- Burst requests fail but spaced requests succeed
Possible causes
- The request rate exceeds the RPM (requests per minute) limit for the tier
- The token usage exceeds the TPM (tokens per minute) limit
- Multiple concurrent workers share the same API key quota
Diagnosis steps
Check the rate limit headers
curl -v https://api.openai.com/v1/chat/completions -H "Authorization: Bearer $KEY"Interpretation
The response headers show x-ratelimit-remaining-requests and reset time.
Review the account usage tier
openai api usage --date $(date +%Y-%m-%d)Interpretation
The tier determines RPM and TPM limits.
Root cause
The OpenAI API enforces per-tier rate limits on requests per minute and tokens per minute; exceeding either triggers a 429 with a retry-after header.
Fix
Implement exponential backoff with jitter, reduce concurrency, cache responses, or request a tier upgrade. Use the retry-after header to schedule retries.
Verify the fix
Send requests within the rate limit and confirm no 429; verify the backoff logic retries correctly after a 429.
Symptom walkthrough
OpenAI returns 429 Too Many Requests because the request rate or token usage exceeds the account tier limit, with a retry-after header indicating when to retry. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.
Diagnosis in practice
Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.
Root cause
The OpenAI API enforces per-tier rate limits on requests per minute and tokens per minute; exceeding either triggers a 429 with a retry-after header.
Fix
Implement exponential backoff with jitter, reduce concurrency, cache responses, or request a tier upgrade. Use the retry-after header to schedule retries. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.
Verification
Send requests within the rate limit and confirm no 429; verify the backoff logic retries correctly after a 429. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.
Diagnostic commands
Run these commands to reproduce and diagnose the issue:
curl -v https://api.openai.com/v1/chat/completions -H "Authorization: Bearer $KEY"
openai api usage --date $(date +%Y-%m-%d)