If your integration backs off on every 429 and the same call still fails an hour later, the backoff is not the problem. A 429 only means "you may not make this request right now", and there are two unrelated families hiding behind that one status code: you are sending requests too quickly, or you have nothing left to spend.
In a log line they look identical. In what you should do next they have nothing in common.
error.type is too coarse. Read error.code.
Billing failures all collapse into the type insufficient_quota, so the type alone cannot tell you whether an organization ran out of prepaid credits or a single project hit its cap. The specific cause lives in error.code:
{
"error": {
"message": "You exceeded your current quota, please check your plan and billing details.",
"type": "insufficient_quota",
"code": "project_spend_limit_exceeded"
}
}
Four billing codes share that type:
error.code |
What actually happened |
|---|---|
credit_balance_exhausted |
The organization has no prepaid credits left |
organization_spend_limit_exceeded |
The organization hit the spend limit someone set on it |
project_spend_limit_exceeded |
One project hit its own spend limit |
organization_usage_limit_exceeded |
The organization reached the usage limit assigned to it |
Two more 429s belong to the other family, and they are not billing problems at all:
error.code / type |
What actually happened |
|---|---|
no code, rate_limit_error
|
You are sending requests too quickly for your RPM or TPM allowance |
slow_down (rate_limit_error) |
Your request rate ramped up faster than the limit climbs |
Retries do not fix billing errors
The docs are blunt about this: retrying billing, spend, or quota errors will not restore API access — you have to update credits or limits before the next request. That is the whole reason the code matters. A retry loop around insufficient_quota is a busy-wait that fills your logs and delays the only action that works.
Rate limits are the opposite: honour Retry-After when it is present, slow the ramp, and the request will go through.
A classifier worth keeping
Because the two families need opposite reactions, branch on the code, not the status:
export function triage(err) {
const e = err?.error ?? err;
const code = e?.code ?? "";
const type = e?.type ?? "";
if (code === "credit_balance_exhausted") return "top_up";
if (code.endsWith("_spend_limit_exceeded")) return "raise_or_wait_for_limit";
if (code === "organization_usage_limit_exceeded") return "request_higher_limit";
if (code === "slow_down" || type === "rate_limit_error") return "back_off";
if (!code) return "inspect_body_before_retrying";
return "unknown";
}
Two details that save time later. First, code can be missing on plain rate-limit responses, so absence of a code is itself a signal — treat it as rate limiting, not as billing. Second, limits are applied per organization rather than per user, so a teammate running a batch job can produce a 429 that your own traffic never earned.
Where the four numbers actually live
The billing codes read like four names for the same trouble, but they are four separate settings, and each one is cleared in a different place:
- Credit balance — the prepaid amount the organization draws down. It is the number people forget to watch after a project spike.
- Organization spend limit — a ceiling on the organization's spend, independent of the balance.
-
Project spend limit — a ceiling on one project, which is why a healthy organization can still return
project_spend_limit_exceededfor one key. - Organization usage limit — assigned to the account rather than chosen by you; when this one is the cause, no amount of topping up changes it.
A key that works on Monday and returns insufficient_quota on Tuesday usually moved from one of these to another, not from "valid" to "invalid".
The sixty-second triage
- Log
status,error.type, anderror.codetogether. Without the code you are guessing. - Score the code into billing or rate. Billing codes never recover on their own.
- For billing, open the balance and the two limits before touching a retry.
- For rate limits, sleep on
Retry-Afterand smooth the ramp. - If the response is a 401 instead, stop — that is a key problem, not a quota problem, and no amount of waiting or topping up will help.
The status code tells you that you were refused. The code inside the body tells you who refused you.
Top comments (0)