Dev.to AI πŸ€– Ai πŸ‘ 0 πŸ“– 3 min read

Your OpenAI API 429 Is Not Always a Rate Limit: Reading insufficient_quota by error.code

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 hid

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_exceeded for 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

  1. Log status, error.type, and error.code together. Without the code you are guessing.
  2. Score the code into billing or rate. Billing codes never recover on their own.
  3. For billing, open the balance and the two limits before touching a retry.
  4. For rate limits, sleep on Retry-After and smooth the ramp.
  5. 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.

πŸ“° Read the original article on Dev.to AI

Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β€” full credit and traffic to the original publisher.