خطاها

وب‌سرویس گیسو خطاها را در همان قالب OpenAI برمی‌گرداند، پس SDK و منطق خطای فعلی‌تان بدون تغییر کار می‌کند. هر خطا یک وضعیت HTTP، یک type کلی و یک code دقیق دارد. در کد روی code تصمیم بگیرید؛ message فارسی و برای خواندن آدم است و ممکن است عوض شود.

قالب خطا

{
  "error": {
    "message": "اعتبار کافی نیست. موجودی $0.0120، مورد نیاز برای این درخواست حداقل $0.0400. حساب خود را شارژ کنید.",
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "param": null
  }
}

• type: یکی از invalid_request_error، authentication_error، permission_error، insufficient_quota، rate_limit_error، upstream_error و service_unavailable.
• param: اگر خطا به یک فیلد مربوط باشد، نام آن فیلد.
• خطایی که وسط پاسخ جریانی پیش بیاید، به شکل رویداد data: {"error": …} در همان جریان می‌آید (پاسخ جریانی).

گرفتن خطا در کد

import openai

try:
    reply = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "Hi"}])
except openai.AuthenticationError as e:          # 401
    print("bad key:", e.code)
except openai.PermissionDeniedError as e:        # 403 (model/IP not allowed, kyc_required)
    print("not allowed:", e.code, e.message)
except openai.RateLimitError as e:               # 429 (after the SDK's own retries)
    print("slow down:", e.response.headers.get("retry-after"))
except openai.APIStatusError as e:               # everything else, e.g. 402 insufficient_credit
    print(e.status_code, e.code, e.message)
    print("request id:", e.request_id)           # the X-Request-Id header

import OpenAI from "openai";

try {
  await client.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "Hi" }] });
} catch (err) {
  if (err instanceof OpenAI.APIError) {
    console.log(err.status, err.code, err.message);           // e.g. 402 insufficient_credit
    console.log(err.request_id);                               // the X-Request-Id header
    if (err.code === "insufficient_credit") notifyAdmin("Top up the Gisoo account");
  } else {
    throw err;
  }
}

همهٔ کدها

400 — درخواست نادرست

401 — کلید

402 — اعتبار و سقف هزینه

403 — اجازه

404 — پیدا نشد

405، 413

429 — سرعت

502، 503 — سرویس‌دهنده یا گیسو

هزینهٔ درخواست ناموفق

خطاهای کلید، اعتبار، محدودیت و درخواست نادرست پیش از رسیدن به سرویس‌دهنده برمی‌گردند و هزینه‌ای ندارند. اگر خود سرویس‌دهنده درخواست را رد کند یا پیش از تولید پاسخ خطا بدهد (upstream_rejected، ۴۲۹ سرویس‌دهنده، ۵۰۲ و ۵۰۳)، مبلغی که برای درخواست کنار گذاشته شده بود کامل برمی‌گردد. تنها استثنا پاسخ جریانی است که وسط کار قطع شود: هزینهٔ بخشی که ساخته و برای شما فرستاده شده حساب می‌شود.

خطایی که هیچ پاسخی ندارد

همهٔ خطاهای بالا یک پاسخ HTTP با بدنهٔ JSON دارند. اگر برنامه‌تان به‌جای آن «timeout»، «connection reset» یا «empty reply» می‌گیرد، درخواست اصلاً به گیسو نرسیده است. معنای هر کد خطای curl و راه آزمایش اتصال از سرور خودتان در اگر وصل نشد آمده است.

پیگیری با پشتیبانی

هر پاسخ، موفق یا ناموفق بعد از رسیدن به سرویس‌دهنده، هدر X-Request-Id دارد. اگر خطایی را نمی‌فهمید، این شناسه را با زمان تقریبی در تیکت بفرستید؛ متن پرامپت لازم نیست و ما هم آن را نداریم.