همهٔ خطاها با قالب استاندارد OpenAI برمیگردند، بنابراین SDKها آنها را به همان استثناهای آشنا تبدیل میکنند. فیلد code دقیقترین راهنما برای واکنش برنامهٔ شماست.
نام پارامتری که مشکل دارد (مثلاً model یا messages[2]) یا null.
پاسخهای ۴۲۹ هدر Retry-After دارند. هیچ خطایی هزینه ندارد؛ فقط درخواستهای موفق محاسبه میشوند.
احراز هویت و دسترسی
code
HTTP
type
معنا
چه کنیم
missing_api_key
401
authentication_error
هدر Authorization (یا X-API-Key) ارسال نشده است.
هدر Authorization: Bearer sk-ntz-v1-… را اضافه کنید.
invalid_api_key
401
authentication_error
کلید وجود ندارد یا نادرست است.
کلید را از پنل کپی کنید؛ فاصله یا کاراکتر اضافی نداشته باشد.
api_key_revoked
401
authentication_error
کلید باطل شده است (بازگشتناپذیر).
کلید جدید بسازید.
api_key_expired
401
authentication_error
تاریخ انقضای کلید گذشته است.
کلید جدید بسازید یا از پشتیبانی تمدید بخواهید.
api_key_disabled
401
authentication_error
کلید از پنل غیرفعال شده است.
کلید را در پنل فعال کنید.
ip_not_allowed
403
permission_error
IP شما در فهرست IPهای مجاز این کلید نیست.
IP سرور را به فهرست اضافه کنید یا فهرست را خالی بگذارید.
too_many_failed_attempts
429
rate_limit_error
بیش از ۲۰ کلید اشتباه در ۱۰ دقیقه از این IP.
چند دقیقه صبر کنید و کلید درست را استفاده کنید.
account_suspended
403
permission_error
حساب API شما معلق شده است.
با پشتیبانی تماس بگیرید.
project_inactive
403
permission_error
پروژهٔ این کلید غیرفعال است.
پروژه را در پنل فعال کنید.
model_not_allowed
403
permission_error
این کلید یا پروژه اجازهٔ استفاده از مدل درخواستی را ندارد.
مدل را به فهرست مدلهای مجاز کلید و پروژه اضافه کنید.
درخواست نامعتبر
code
HTTP
type
معنا
چه کنیم
invalid_json
400
invalid_request_error
بدنهٔ درخواست JSON معتبر نیست.
Content-Type: application/json و JSON درست بفرستید.
request_too_large
413
invalid_request_error
بدنهٔ درخواست از حد مجاز (۲۰ مگابایت) یا فایل صوتی از ۲۵ مگابایت بزرگتر است.
تصاویر را با URL بفرستید، تاریخچه را کوتاه کنید یا فایل را تکهتکه کنید.
missing_model
400
invalid_request_error
فیلد model ارسال نشده است.
شناسهٔ مدل را بفرستید.
invalid_model
400
invalid_request_error
نام مدل نامعتبر (بیش از حد بلند) است.
شناسه را از فهرست مدلها بردارید.
model_not_found
404
invalid_request_error
مدل وجود ندارد یا در حال حاضر در دسترس نیست.
GET /models را ببینید؛ شناسهٔ دقیق یا شکل کامل provider/slug را بفرستید. شناسهٔ Claude و بقیهٔ مدلهای OpenRouter با openrouter/ شروع میشود.
model_discontinued
404
invalid_request_error
این مدل را قبلاً ارائه میکردیم و دیگر روی درگاه نیست (مثلاً dall-e-3 یا claude-sonnet-4-5).
نزدیکترین مدل فعال همان سازنده را از GET /models بردارید؛ فهرست کامل در صفحهٔ مدلها و قیمتها.
model_endpoint_mismatch
400
invalid_request_error
نوع مدل با endpoint نمیخواند (مثلاً مدل امبدینگ در /chat/completions).
مدل مناسب همان endpoint را انتخاب کنید.
missing_messages
400
invalid_request_error
فیلد messages خالی یا ارسال نشده است.
حداقل یک پیام بفرستید.
invalid_message
400
invalid_request_error
یکی از پیامها role ندارد یا ساختارش نادرست است.
هر پیام باید role و content داشته باشد.
too_many_messages
400
invalid_request_error
تعداد پیامها از سقف مجاز بیشتر است.
تاریخچه را خلاصه کنید.
missing_prompt
400
invalid_request_error
فیلد prompt (در /completions یا /images) خالی است.
prompt را بفرستید.
missing_input
400
invalid_request_error
فیلد input (در /embeddings، /responses، /moderations، /audio/speech) خالی است.
input را بفرستید.
input_too_long
400
invalid_request_error
متن ورودی متنبهگفتار از سقف مدل بیشتر است: ۴٬۰۹۶ کاراکتر، و در Gemini TTS ۳٬۰۰۰ کاراکتر (capabilities.max_input_chars).
متن را تکهتکه کنید.
invalid_seconds
400
invalid_request_error
مدت ویدیو برای این مدل یا این قاب مجاز نیست؛ مثلاً Veo در 1080p و 4K فقط ۸ ثانیه میسازد.
یکی از مقدارهای capabilities.seconds (و seconds_by_size) همان مدل را بفرستید؛ هزینهای کم نشده است.
invalid_size
400
invalid_request_error
این مدل ویدیو را در قاب درخواستی نمیسازد (مثلاً 4K روی veo-3.1-lite).
یکی از مقدارهای capabilities.sizes همان مدل را بفرستید.
missing_file
400
invalid_request_error
فیلد file در درخواست صوتی ارسال نشده است.
فایل را با multipart/form-data و نام فیلد file بفرستید.
invalid_file
400
invalid_request_error
فایل آپلودشده معتبر نیست.
فرمت و سلامت فایل را بررسی کنید.
streaming_disabled
400
invalid_request_error
استریم موقتاً غیرفعال است.
همان درخواست را با stream: false بفرستید.
upstream_rejected
400
invalid_request_error
ارائهدهنده درخواست را رد کرد (پارامتر یا محتوای نامعتبر)؛ از جمله وقتی فیلتر محتوایی گوگل تصویر یا قطعهٔ موسیقی را نمیسازد. پیام ارائهدهنده در message میآید و هزینهای کم نمیشود.
پارامترها را طبق مستندات مدل اصلاح کنید؛ اگر فیلتر محتوا بوده، توصیف را تغییر دهید.
اعتبار و سقفها
code
HTTP
type
معنا
چه کنیم
insufficient_credit
402
insufficient_quota
اعتبار برای رزرو این درخواست کافی نیست.
حساب را شارژ کنید یا max_tokens را کم کنید تا رزرو کوچکتر شود.
key_spend_limit_reached
402
insufficient_quota
سقف هزینهٔ تعیینشده برای این کلید پر شده است.
سقف را در صفحهٔ پروژه، با دکمهٔ «سقف هزینه» کنار همان کلید، بالا ببرید یا بردارید. رزرو پیش از هر درخواست هم با سقف سنجیده میشود؛ با max_tokens کوچکتر، رزرو کوچکتر است.
project_budget_exceeded
402
insufficient_quota
بودجهٔ ماهانهٔ پروژه تمام شده است.
بودجه را افزایش دهید یا تا ماه بعد صبر کنید.
daily_cap_reached
402
insufficient_quota
سقف مصرف روزانهٔ حساب پر شده است.
فردا دوباره تلاش کنید یا از پشتیبانی افزایش بخواهید.
free_quota_exceeded
429
rate_limit_error
سقف روزانهٔ درخواست به مدلهای رایگان پر شده است. فعلاً مدل رایگانی ارائه نمیشود، پس این خطا نباید پیش بیاید.
از نسخهٔ پولی همان مدل استفاده کنید.
نرخ و ظرفیت
code
HTTP
type
معنا
چه کنیم
rate_limit_exceeded
429
rate_limit_error
بیش از حد مجاز درخواست در دقیقه (برای کلید یا IP).
به اندازهٔ Retry-After صبر کنید؛ در صورت نیاز افزایش RPM بخواهید.
concurrency_limit
429
rate_limit_error
تعداد درخواستهای همزمان حساب از حد مجاز بیشتر است.
درخواستها را صفبندی کنید یا افزایش همزمانی بخواهید.
upstream_rate_limited
429
rate_limit_error
ظرفیت ارائهدهندهٔ این مدل موقتاً پر است.
چند ثانیه بعد دوباره تلاش کنید یا مدل جایگزین بفرستید.
upstream_capacity_full
429
rate_limit_error
ارائهدهندهٔ این مدل شلوغ است و درخواست را نپذیرفت. مثل upstream_rate_limited فقط به همین مدل مربوط است، نه به کلید یا حساب شما، و هزینهای ندارد.
به اندازهٔ Retry-After صبر کنید یا مدل دیگری بفرستید.
daily_capacity_reached
503
service_unavailable
ظرفیت روزانهٔ کل سرویس تکمیل شده است (نادر).
فردا دوباره تلاش کنید.
gateway_disabled
503
service_unavailable
سرویس API موقتاً غیرفعال است (نگهداری).
کمی بعد دوباره تلاش کنید.
model_temporarily_unavailable
503
service_unavailable
ارائهدهنده درخواست نِت اَرز را رد کرد؛ تیم فنی مطلع شده است.
مدل جایگزین (مثلاً از ارائهدهندهٔ دیگر) بفرستید و کمی بعد دوباره امتحان کنید.
خطاهای ارائهدهنده (بدون هزینه)
code
HTTP
type
معنا
چه کنیم
upstream_unreachable
502
upstream_error
اتصال به ارائهدهنده برقرار نشد یا زمان انتظار تمام شد.
دوباره تلاش کنید؛ هزینهای کسر نشده است.
upstream_error
502
upstream_error
ارائهدهنده با خطای داخلی پاسخ داد یا پاسخ نامعتبر بود.
دوباره تلاش کنید؛ هزینهای کسر نشده است.
stream_interrupted
۲۰۰ (داخل استریم)
upstream_error
ارتباط با ارائهدهنده در میانهٔ استریم قطع شد؛ بهصورت رویداد data: {"error": …} ارسال میشود.
توکنهای دریافتشده را نگه دارید و در صورت نیاز درخواست را تکرار کنید.
gateway_error
502
upstream_error
خطای داخلی در پردازش درخواست پس از ارسال.
دوباره تلاش کنید؛ هزینهای کسر نشده است.
internal_error
502
upstream_error
خطای غیرمنتظره در درگاه.
با شناسهٔ درخواست به پشتیبانی اطلاع دهید.
حساب و مصرف
code
HTTP
type
معنا
چه کنیم
request_not_found
404
invalid_request_error
درخواستی با این شناسه در پروژهٔ شما وجود ندارد.
شناسهٔ req_… و کلید همان پروژه را بررسی کنید.
مدیریت خطا در کد
Python
from openai import OpenAI, APIStatusError, AuthenticationError, RateLimitError
client = OpenAI(base_url="https://netarz.ir/api/ai/v1", api_key="sk-ntz-v1-...")
try:
r = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "سلام"}])
except AuthenticationError as e: # 401
print("کلید نامعتبر:", e.body["error"]["code"])
except RateLimitError as e: # 429 — با Retry-After دوباره تلاش کنید
print("صبر کنید:", e.response.headers.get("Retry-After"))
except APIStatusError as e: # هر خطای دیگر
code = e.body["error"]["code"] if e.body else None
if e.status_code == 402:
print("اعتبار کافی نیست یا سقف مصرف پر شده:", code)
elif e.status_code >= 500:
print("خطای ارائهدهنده (بدون هزینه) — تلاش مجدد:", code)
else:
print(e.status_code, code, e.body["error"]["message"])
۴۲۹: با backoff نمایی و احترام به Retry-After تکرار کنید.
۵۰۲/۵۰۳: رایگان بودهاند؛ یک یا دو بار با فاصله تکرار کنید یا مدل جایگزین بفرستید.