پرش به محتوا

خطاها

همهٔ کدهای خطای وب‌سرویس گیسو با وضعیت HTTP، معنا و راه رفع؛ قالب خطا که همان قالب OpenAI است، و این‌که کدام خطاها را دوباره بفرستید.

بازبینی: ۸ مهر ۱۴۰۵ ۶ دقیقه مطالعه

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

قالب خطا#

JSON پاسخ خطا
{
  "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

همهٔ کدها#

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

invalid_json
بدنه JSON معتبر نیست، یا با UTF-16 یا کدگذاری غیر از UTF-8 فرستاده شده است.
بدنه را JSON درست و UTF-8 بفرستید.
missing_model invalid_model
فیلد model نیست یا نامعتبر است.
شناسه را از GET /models بردارید.
model_endpoint_mismatch
مدل مال endpoint دیگری است (مثلاً مدل ویدیو به chat).
متن خطا endpoint درست را می‌گوید.
missing_messages invalid_message too_many_messages
messages خالی است، پیامی role ندارد یا تعدادشان زیاد است.
ساختار پیام‌ها را بررسی کنید.
missing_prompt missing_input missing_file
فیلد الزامی آن endpoint نیامده است.
param خطا نام فیلد را می‌گوید.
prompt_too_long input_too_long
توصیف ویدیو یا موسیقی بیش از ۴٬۰۰۰ نویسه، یا متن گفتار بیش از ۴٬۰۹۶ نویسه است.
متن را کوتاه یا تکه‌تکه کنید.
invalid_seconds invalid_size
مدت یا اندازهٔ ویدیو برای این مدل مجاز نیست.
مقدارهای مجاز در متن خطا آمده است.
streaming_disabled
پاسخ جریانی موقتاً خاموش است.
تا روشن شدنش stream: false بفرستید.
upstream_rejected
سرویس‌دهندهٔ مدل درخواست را نپذیرفت (پارامتر پشتیبانی‌نشده، سیاست محتوایی).
متن خطا دلیل سرویس‌دهنده را می‌گوید؛ هزینه‌ای کم نشده است.
endpoint_not_supported
مدل‌های این سازنده این endpoint را ندارند.
مدل یا endpoint دیگری انتخاب کنید.

401 — کلید#

missing_api_key
کلیدی فرستاده نشده است.
هدر Authorization: Bearer … را بفرستید.
invalid_api_key
کلید درست نیست.
کلید را کامل و بدون فاصله کپی کنید.
api_key_revoked api_key_expired api_key_disabled
کلید باطل، منقضی یا خاموش است.
کلید تازه بسازید.

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

insufficient_credit
موجودی برای برآورد این درخواست کافی نیست.
حساب را شارژ کنید یا max_tokens را کمتر بگذارید.
key_spend_limit_reached
سقف هزینهٔ این کلید پر شده است.
سقف را بالا ببرید یا کلید دیگری بسازید.
project_budget_exceeded
بودجهٔ ماهانهٔ پروژه تمام شده است.
بودجه را در تنظیمات پروژه بالا ببرید.
daily_cap_reached
سقف هزینهٔ روزانهٔ حساب پر شده است.
فردا دوباره بفرستید، یا برای تغییر سقف تیکت بفرستید.

403 — اجازه#

model_not_allowed
این کلید یا پروژه اجازهٔ این مدل را ندارد.
مدل را به فهرست مجاز کلید و پروژه اضافه کنید.
ip_not_allowed
IP درخواست در فهرست مجاز کلید نیست.
IP سرور را به کلید اضافه کنید.
kyc_required
سقف مصرف پیش از احراز هویت پر شده است.
احراز هویت را در اپ گیسو کامل کنید.
project_inactive account_suspended
پروژه خاموش یا حساب معلق است.
پروژه را روشن کنید؛ برای حساب معلق تیکت بفرستید.

404 — پیدا نشد#

model_not_found
مدلی با این شناسه در فروش نیست.
شناسه را از GET /models بردارید.
model_discontinued
این مدل قبلاً فروخته می‌شد و حالا برداشته شده است.
مدل دیگری انتخاب کنید.
request_not_found video_not_found
درخواست یا ویدیو در این پروژه نیست.
شناسه و کلید پروژه را بررسی کنید.
unknown_url
چنین endpointی وجود ندارد.
نشانی را با مرجع API مقایسه کنید.

405، 413#

method_not_allowed
endpoint درست است ولی روش HTTP نه (مثلاً GET به‌جای POST).
هدر Allow روش درست را می‌گوید.
request_too_large
حجم درخواست از سقف بیشتر است.
تصویر یا صدا را کوچک کنید؛ فایل صوتی تا ۲۵ مگابایت.

429 — سرعت#

rate_limit_exceeded
سقف درخواست در دقیقه (کلید یا IP) پر شده است.
به اندازهٔ Retry-After صبر کنید.
concurrency_limit
درخواست‌های همزمان حساب از سقف بیشتر است.
همزمانی را در کد محدود کنید.
upstream_rate_limited upstream_capacity_full
ظرفیت سرویس‌دهندهٔ همین مدل موقتاً پر است.
چند ثانیه بعد یا با مدل دیگری امتحان کنید؛ هزینه‌ای کم نشده است.
too_many_failed_attempts
کلیدهای نادرست زیادی از این IP آمده است.
چند دقیقه صبر کنید و کلید را بررسی کنید.

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

upstream_error upstream_unreachable
سرویس‌دهندهٔ مدل پاسخ نداد یا خطا داد.
دوباره بفرستید؛ هزینه‌ای کم نشده است.
stream_interrupted
اتصال سرویس‌دهنده وسط پاسخ جریانی قطع شد (رویداد error در جریان).
دوباره بفرستید؛ فقط بخش ساخته‌شده حساب می‌شود.
model_temporarily_unavailable
این مدل موقتاً در دسترس نیست و تیم فنی خبر دارد.
کمی بعد یا با مدل دیگری امتحان کنید.
gateway_disabled daily_capacity_reached
وب‌سرویس موقتاً بسته یا ظرفیت روزانه‌اش پر است.
کمی بعد دوباره امتحان کنید.
internal_error gateway_error
خطای پیش‌بینی‌نشده در گیسو.
با X-Request-Id تیکت بفرستید.

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

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

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

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

پاسخ پرسشتان را پیدا نکردید؟

شناسهٔ درخواست (هدر X-Request-Id) را با پرسشتان در تیکت بفرستید تا دقیق بررسی کنیم.

تیکت پشتیبانی