Limits and errors

Every error is a sentence saying what happened and whose move it is. Let's learn to read them.

6 minLesson 8 of 80 of 3 steps

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 fromControls
Rate limitYour planSpeed: requests per minute, hour and day, and tokens per minute
BudgetA key, workspace or guardrailTotal 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

CodeMeansWhat to do
401 invalid_api_keyWrong, revoked or expired keyMost common cause: a stray space or newline from copying
402 insufficient_balanceNot enough balance for the holdTop up, or lower max_tokens
402 plan_quota_reachedThe plan's allowance is spentRenew, or switch the key to credit
403 model_not_in_planThis model isn't in your planSwitch the key to credit
404 model_not_foundThe model id is wrongCopy the id from the models page
429 rate_limit_*Requests are too fastHonour retry-after
429 key_daily_budget_reachedThe key's daily cap is fullWait for midnight Tehran time or raise the cap
503 no_capacityNo healthy route for this model right nowSend 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.
An agent that retries without waiting fills its own limit faster. Always honour the 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

  1. Send one request with a wrong model id.
  2. See the error code in the response.
  3. 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.
Holds and settlement: why max_tokens is moneyOne small number in your request decides how many concurrent calls your balance can carry.Done, next lesson