Limits and errors
Every error is a sentence saying what happened and whose move it is. Let's learn to read them.
An error here isn't a meaningless sentence. Every error response has a code that says exactly what happened and whose move it is. Learning these few codes clears most problems.
Two kinds of limit
| Comes from | Controls | |
|---|---|---|
| Rate limit | Your plan | Speed: requests per minute, hour and day, and tokens per minute |
| Budget | A key, workspace or guardrail | Total spend |
They're independent, and either can refuse a request. To see every limit on a key at once, open it and choose Everything that applies. The strictest number wins.
What the errors mean
| Code | Means | What to do |
|---|---|---|
401 invalid_api_key | Wrong, revoked or expired key | Most common cause: a stray space or newline from copying |
402 insufficient_balance | Not enough balance for the hold | Top up, or lower max_tokens |
402 plan_quota_reached | The plan's allowance is spent | Renew, or switch the key to credit |
403 model_not_in_plan | This model isn't in your plan | Switch the key to credit |
404 model_not_found | The model id is wrong | Copy the id from the models page |
429 rate_limit_* | Requests are too fast | Honour retry-after |
429 key_daily_budget_reached | The key's daily cap is full | Wait for midnight Tehran time or raise the cap |
503 no_capacity | No healthy route for this model right now | Send it again a little later |
Read the code, not the message text. The code is stable, and your program's decisions belong on it.
When to retry
- Worth it: 429 after
retry-after, and 503 or 502 with a gradually growing delay. - Pointless: 400, 401, 403 and 404. The answer won't change until the request does.
- Needs a person: 402. Someone must top up or change a setting.
retry-after header.For support
Every response has an x-request-id header. If you open a ticket, send that. The full list of codes is in the error reference.
See an error on purpose0 of 3 steps
- Send one request with a wrong model id.
- See the error code in the response.
- Find that request in the logs and see whose side it's marked as.
What you learned
- A rate limit controls speed; a budget controls spend.
- The error code says what to do.
- That's Intermediate. Advanced is for those who take cost and reliability seriously.
Keep your place
Sign in to the panel and each lesson and your path are saved, so you continue from the same spot on any device.