خطاها و کدها — ۴۰۰ تا ۵۰۴ و راه‌حل هر کدام

همهٔ خطاها با همان شکل خطای OpenAI برمی‌گردند تا SDKها آن‌ها را به exception درست تبدیل کنند. فرق ما یک بلوک اضافه به نام uttapen است که در بعضی خطاها اطلاعات عملی می‌دهد (مثلاً مبلغ لازم و لینک شارژ).

شکل خطا

{
  "error": {
    "message": "موجودی کافی نیست. برای این درخواست حدود 151٬656 تومان لازم است و موجودی قابل‌استفاده 97٬518 تومان است.",
    "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 و type همیشه یکی‌اند؛ روی code شرط بگذار.
• message فارسی و برای نمایش به کاربر نهایی مناسب است. پیام‌هایی که از provider می‌آیند انگلیسی‌اند.
• uttapen فقط وقتی هست که چیزی برای گفتن داریم؛ روی وجودش شرط بگذار.
• هدر X-Uttapen-Request-Id روی خطاها هم هست. برای گزارش مشکل همین را بفرست.

جدول خطاها

خطاهای 5xx و 429 امن برای تکرارند: هیچ‌کدام بدون این که پاسخ بگیری هزینه‌ای برایت نمی‌گذارند. 400 و 401 و 403 و 404 را تکرار نکن؛ نتیجه همان است.

هزینه در خطا

قاعده ساده است: اگر پاسخ نگرفتی، پول نداده‌ای. رزرو در خطاهای قبل از ارسال اصلاً انجام نمی‌شود و در خطاهای provider همان لحظه آزاد می‌شود. تنها استثنا خطای وسط استریم است که بخشی از پاسخ رسیده؛ آن‌جا فقط مصرف واقعی تا لحظهٔ قطع تسویه می‌شود (استریم).

نگاشت به SDKها

Python (openai) — هر status به یک کلاس:

import openai

try:
    resp = client.chat.completions.create(model="openai/gpt-5-mini", messages=msgs)
except openai.AuthenticationError:
    raise SystemExit("کلید uttapen نامعتبر است")
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("موجودی کافی نیست؛ لازم:", info["required_toman"], "تومان —", info["topup_url"])
    else:
        print(e.status_code, e.code, e.message)

e.code همان error.code ماست، e.body کل بدنهٔ JSON و e.response.headers هدرها (شامل x-uttapen-request-id). SDK به‌صورت پیش‌فرض 429 و 5xx را دو بار با backoff تکرار می‌کند؛ با max_retries تنظیمش کن.

Node.js (openai) — همان نام‌ها: AuthenticationError، RateLimitError، NotFoundError، BadRequestError، PermissionDeniedError، InternalServerError؛ برای 402 کلاس عمومی APIError با err.status === 402. err.code و err.error.uttapen در دسترس‌اند.

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) — همهٔ خطاهای HTTP OpenAI\Exceptions\ErrorException هستند با getStatusCode()، getErrorCode() و getMessage(). بلوک uttapen را این کلاینت نگه نمی‌دارد؛ برای 402 مبلغ را از پیام بخوان یا با Guzzle خام بدنه را بگیر.

Go (openai-go) — var apierr *openai.Error; errors.As(err, &apierr) سپس apierr.StatusCode، apierr.Code، apierr.Message و apierr.RawJSON() برای بلوک uttapen.

توصیه برای کد تولیدی

• روی code شرط بگذار نه روی متن message؛ متن ممکن است تغییر کند.
• برای 429 و 5xx backoff نمایی با jitter و حداکثر سه تلاش. Retry-After را اگر بود، رعایت کن.
• 402 را به کاربر یا ادمین خودت نشان بده و تکرار نکن؛ تا شارژ نشود همان می‌ماند.
• X-Uttapen-Request-Id را در لاگ خودت کنار خطا بنویس. وقتی از پشتیبانی می‌پرسی، با همین شناسه در چند ثانیه پیدایش می‌کنیم.
• قبل از deploy، GET /v1/uttapen/me را بزن تا کلید، مدل مجاز و موجودی را یک‌جا ببینی.