Error codes — 400 to 504 and what to do

Every error comes back in OpenAI's error shape, so the SDKs turn it into the exception you expect. The one thing we add is an extra uttapen block, which carries something actionable on the errors where that helps — the amount you're short and a top-up link, for instance.

Error shape

{
  "error": {
    "message": "Insufficient balance. This request needs about 151,656 toman and your available balance is 97,518 toman.",
    "type": "insufficient_balance",
    "code": "insufficient_balance",
    "param": null,
    "uttapen": {
      "balance_toman": "97517.828964",
      "available_toman": "97517.828964",
      "required_toman": "151656.439570",
      "topup_url": "https://uttapen.ir/dashboard/wallet"
    }
  }
}

• code and type always hold the same value; branch on code.
• message is written for humans and is fine to surface to an end user. Messages that originate at the provider are passed through as they arrive.
• uttapen is present only when we have something useful to add, so check for it before reading it.
• The X-Uttapen-Request-Id header is set on errors too. Send it along when you report a problem.

The error table

5xx and 429 are safe to retry: none of them cost you anything unless you actually received a response. Don't retry 400, 401, 403 or 404 — the outcome will be identical.

What errors cost

The rule is simple: no response, no charge. Errors raised before the request goes out never place a hold at all, and errors from the provider release the hold immediately. The single exception is a failure part-way through a stream, where some of the response did arrive: there, only what was actually consumed up to the cut is settled (streaming).

How the SDKs raise it

Python (openai) — one class per status:

import openai

try:
    resp = client.chat.completions.create(model="openai/gpt-5-mini", messages=msgs)
except openai.AuthenticationError:
    raise SystemExit("The uttapen API key is invalid")
except openai.RateLimitError as e:
    wait = int(e.response.headers.get("retry-after", "5"))
    time.sleep(wait)
except openai.APIStatusError as e:
    if e.status_code == 402:
        info = e.body["error"]["uttapen"]
        print("Insufficient balance; needed:", info["required_toman"], "toman —", info["topup_url"])
    else:
        print(e.status_code, e.code, e.message)

e.code is our error.code, e.body is the whole JSON body, and e.response.headers gives you the headers, x-uttapen-request-id included. By default the SDK retries 429 and 5xx twice with backoff; tune that with max_retries.

Node.js (openai) — the same names: AuthenticationError, RateLimitError, NotFoundError, BadRequestError, PermissionDeniedError, InternalServerError. For 402 you get the generic APIError with err.status === 402. Both err.code and err.error.uttapen are available.

try {
  await client.chat.completions.create({ model: "openai/gpt-5-mini", messages });
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.error(err.status, err.code, err.error?.uttapen);
  } else throw err;
}

PHP (openai-php/client) — every HTTP error arrives as OpenAI\Exceptions\ErrorException with getStatusCode(), getErrorCode() and getMessage(). This client drops the uttapen block, so for 402 either read the amount out of the message or fetch the raw body with Guzzle.

Go (openai-go) — var apierr *openai.Error; errors.As(err, &apierr), then apierr.StatusCode, apierr.Code, apierr.Message, and apierr.RawJSON() for the uttapen block.

Advice for production code

• Branch on code, never on the text of message — wording can change.
• For 429 and 5xx, use exponential backoff with jitter and at most three attempts. Respect Retry-After when it's there.
• Surface 402 to your user or your own admin and stop retrying; nothing changes until the wallet is topped up.
• Log X-Uttapen-Request-Id next to the error on your side. Give us that id and we'll find the request in seconds.
• Before you deploy, call GET /v1/uttapen/me once to see the key, its allowed models and the balance in one place.