خطاها و تلاش مجدد

قالب خطا#

{
  "error": {
    "message": "Model `openai/gpt-9` does not exist or is not available. See GET /v1/models.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": null
  }
}

جدول کدها#

خطا در میانهٔ استریم#

وقتی استریم شروع شده باشد (کد 200 ارسال شده)، خطای بعدی پروایدر به‌صورت یک رویداد SSE می‌آید و بلافاصله [DONE] ارسال می‌شود. در این رویداد code کد وضعیت HTTP پروایدر (عدد) است:

data: {"id":"chatcmpl-x","object":"chat.completion.chunk",...,"choices":[{"index":0,"delta":{"content":"بخشی از"},...}]}

data: {"error":{"message":"Overloaded","type":"upstream_error","code":529}}

data: [DONE]

SDKهای رسمی OpenAI این رویداد را به exception تبدیل می‌کنند. اگر خودت SSE را می‌خوانی، هر data را برای کلید error بررسی کن. درخواست‌هایی که با خطا تمام شوند هزینه‌ای ندارند.

راهنمای تلاش مجدد#

• فقط روی 429، 5xx و خطاهای شبکه تلاش مجدد کن؛ 4xxهای دیگر با تکرار درست نمی‌شوند.
• در 429 با کد rate_limit_exceeded، به اندازهٔ هدر Retry-After (ثانیه) صبر کن.
• در بقیهٔ موارد از exponential backoff با jitter استفاده کن (مثلاً ۱، ۲، ۴، ۸ ثانیه + عدد تصادفی) و حداکثر ۴–۵ بار.
• برای پایداری بیشتر، بعد از چند شکست به یک مدل جایگزین از پروایدر دیگر سوییچ کن (نمونهٔ fallback).
• شناسهٔ X-Request-Id پاسخ را لاگ کن تا پشتیبانی بتواند درخواست را پیدا کند.

نمونه کد#

from openai import OpenAI

# SDK رسمی خودش روی 408/409/429/5xx با backoff تلاش مجدد می‌کند
client = OpenAI(base_url="https://api.hooshi.ai/v1", api_key="hk-...", max_retries=4, timeout=120)

import openai
try:
    r = client.chat.completions.create(model="openai/gpt-5.5", messages=[{"role": "user", "content": "سلام"}])
except openai.AuthenticationError:
    ...  # 401: کلید را بررسی کن
except openai.PermissionDeniedError as e:
    ...  # 403: ip_not_allowed یا model_not_allowed
except openai.APIStatusError as e:
    if e.status_code == 402:
        code = e.body.get("code") if isinstance(e.body, dict) else None
        ...  # insufficient_quota یا spend_limit_reached → هشدار به تیم
    else:
        raise