insufficient_quota: fixing OpenAI's 429 billing error

The short version

• insufficient_quota is an OpenAI 429 caused by credit or spend limits. Waiting does not clear it.
• A rate-limit 429 recovers with time. Only that kind belongs in a retry loop.
• OpenAI's guide says to inspect error.code for billing errors, because error.type can stay insufficient_quota as a broad category.
• The fix is to add credits or raise the organization or project limit.

What the error looks like

A March 2026 report on OpenAI's developer forum shows this body with HTTP 429:

{
  "error": {
    "message": "You exceeded your current quota, please check your plan and billing details. For more information on this error, read the docs: https://platform.openai.com/docs/guides/error-codes/api-errors.",
    "type": "insufficient_quota",
    "param": null,
    "code": "insufficient_quota"
  }
}

How it differs from a rate limit

Check error.code

OpenAI's error code guide lists these billing-related 429s:

If the dashboard shows credit but the error persists, check which project the key belongs to and whether that project has its own limit.

Keep billing errors out of your retries

Sending this through your rate-limit handler means waiting on something that will never recover. Split it out as soon as you catch RateLimitError:

import os

from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key=os.environ["FASTMETAL_API_KEY"],
    base_url="https://api.fastmetal.ai/v1",
)

BILLING_CODES = {
    "insufficient_quota",
    "credit_balance_exhausted",
    "organization_spend_limit_exceeded",
    "project_spend_limit_exceeded",
    "organization_usage_limit_exceeded",
}


def is_billing_error(err: RateLimitError) -> bool:
    return err.code in BILLING_CODES or err.type == "insufficient_quota"


try:
    resp = client.chat.completions.create(
        model="deepseek-v4.1-flash",
        messages=[{"role": "user", "content": "Hello"}],
        max_tokens=64,
    )
    print(resp.choices[0].message.content)
except RateLimitError as err:
    if is_billing_error(err):
        raise SystemExit(f"Check your billing settings: {err.code}")
    raise

The official OpenAI SDK retries 429s automatically, so lower max_retries if you do not want it waiting on billing errors.

How prepaid credit works on FastMetal

FastMetal is prepaid, and your balance is your spending cap, so a bill above the balance cannot happen. When the balance runs out, requests are refused.

You get an email when the balance runs low and another when it runs out, including for API-only use. Each API key can have its own balance cap, which stops one project from draining the whole account.

The minimum top-up is $5 by card, reflected immediately. The free model gemini-flash-lite-free costs $0 and works without a top-up. Per-token rates are on the pricing page.

FAQ

Will insufficient_quota go away if I wait?

Not if you are out of credit. A monthly spend limit clears at reset. error.code tells you which one you have.

I added credit and still get the error. Why?

Confirm that the key belongs to the same organization and project that received the credit, and look for a separate project spend limit.

How do I tell it apart from a rate limit?

Use error.code and error.type. Both are 429, so the status alone cannot separate them.

What happens on FastMetal when the balance reaches zero?

Requests are refused and nothing is charged beyond the balance. Top up and the same key keeps working.

Wrapping up

insufficient_quota shares a status with rate limits and nothing else. Keep it out of your retries, read error.code, and fix the credit or the limit.

To start on a prepaid balance, create a free account.