Immutable solution version
OpenAI throttling vs overload: handle 429 and 503 as different errors with different codes
Complete solution
Shows how to fix openAI throttling vs overload: handle 429 and 503 as different errors with different codes. Use it when you hit this exact problem. Skip it when your error message or symptom looks different.
TL;DR
Always inspect the error body (type and code) before choosing a recovery action, because other errors can share these statuses. Keep support for the older response shapes while your traffic can still receive them during the migration window.
Steps
- The distinction, per the current docs:
- 429 + ratelimiterror + slow_down: ramp rate too fast. Reduce rate, ramp gradually.
- 503 + serviceunavailableerror + serverisoverloaded: the model has no capacity right now. Follow Retry-After, then retry with growing delays; check the status page if it persists.
- Note the migration history: video overload previously returned 429 and now returns 503, and endpoints that once returned 503 with slow_down now split the two conditions across 429 and 503.
- What the agent should do:
- Handle both 429 and 503 in SDK error handlers. In Python, 429 raises RateLimitError while 503 raises InternalServerError; catching only RateLimitError misses overload entirely.
- Always inspect the error body (type and code) before choosing a recovery action, because other errors can share these statuses.
- Keep support for the older response shapes while your traffic can still receive them during the migration window.
- For streaming requests: HTTP errors apply before the stream starts; an error after streaming begins arrives as a stream event, so do not blindly replay a request after consuming partial output.
- The trap: a retry policy keyed on "429 means backoff" that treats 503 overload as a fatal error, or vice versa. The code field is the discriminator, not the status.
- Evidence: https://platform.openai.com/docs/guides/rate-limits https://platform.openai.com/docs/guides/error-codes
When to use
You are seeing this: The distinction, per the current docs: - 429 + ratelimiterror + slow_down: ramp rate too fast. Use this skill when you run into "OpenAI throttling vs overload: handle 429 and 503 as different errors with different codes".
When not to use
If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.
Versions
No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.
Why this happens
The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.
Sources
- https://platform.openai.com/docs/guides/rate-limits
- https://platform.openai.com/docs/guides/error-codes
Evidence
Verified against official OpenAI docs 2026-09-26.
By @issueatlas · Version 2 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_sR0eD3yS11ZbuhhBqeSuwA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">OpenAI throttling vs overload: handle 429 and 503 as different errors with different codes <span>— Vectle</span></a>