نِت اَرز · مستندات API هوش مصنوعی
همهٔ مستندات
مدل‌ها و قیمت‌ها مرجع تعاملی دریافت کلید

خطاها

همهٔ کدهای خطای API هوش مصنوعی نِت اَرز با وضعیت HTTP، معنای هر خطا و راه رفع آن؛ پاسخ خطا همان قالب OpenAI را دارد و کد فعلی شما آن را می‌شناسد.

base_url: https://netarz.ir/api/ai/v1 به‌روزرسانی: 1405/08/09

همهٔ خطاها با قالب استاندارد OpenAI برمی‌گردند، بنابراین SDKها آن‌ها را به همان استثناهای آشنا تبدیل می‌کنند. فیلد code دقیق‌ترین راهنما برای واکنش برنامهٔ شماست.

قالب خطا
HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Powered-By: NetArz AI Gateway

{
  "error": {
    "message": "اعتبار کافی نیست.",
    "type": "insufficient_quota",
    "code": "insufficient_credit",
    "param": null
  }
}
فیلدتوضیح
messageتوضیح فارسی برای انسان (متن آن ممکن است تغییر کند؛ به آن وابسته نشوید).
typeدستهٔ خطا: invalid_request_error، authentication_error، permission_error، insufficient_quota، rate_limit_error، upstream_error، service_unavailable.
codeکد ماشین‌خوان و پایدار (جدول‌های زیر).
paramنام پارامتری که مشکل دارد (مثلاً model یا messages[2]) یا null.

پاسخ‌های ۴۲۹ هدر Retry-After دارند. هیچ خطایی هزینه ندارد؛ فقط درخواست‌های موفق محاسبه می‌شوند.

احراز هویت و دسترسی

codeHTTPtypeمعناچه کنیم
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 این کلید یا پروژه اجازهٔ استفاده از مدل درخواستی را ندارد. مدل را به فهرست مدل‌های مجاز کلید و پروژه اضافه کنید.

درخواست نامعتبر

codeHTTPtypeمعناچه کنیم
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 می‌آید و هزینه‌ای کم نمی‌شود. پارامترها را طبق مستندات مدل اصلاح کنید؛ اگر فیلتر محتوا بوده، توصیف را تغییر دهید.

اعتبار و سقف‌ها

codeHTTPtypeمعناچه کنیم
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 سقف روزانهٔ درخواست به مدل‌های رایگان پر شده است. فعلاً مدل رایگانی ارائه نمی‌شود، پس این خطا نباید پیش بیاید. از نسخهٔ پولی همان مدل استفاده کنید.

نرخ و ظرفیت

codeHTTPtypeمعناچه کنیم
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 ارائه‌دهنده درخواست نِت اَرز را رد کرد؛ تیم فنی مطلع شده است. مدل جایگزین (مثلاً از ارائه‌دهندهٔ دیگر) بفرستید و کمی بعد دوباره امتحان کنید.

خطاهای ارائه‌دهنده (بدون هزینه)

codeHTTPtypeمعناچه کنیم
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 خطای غیرمنتظره در درگاه. با شناسهٔ درخواست به پشتیبانی اطلاع دهید.

حساب و مصرف

codeHTTPtypeمعناچه کنیم
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 تکرار کنید.
  • ۵۰۲/۵۰۳: رایگان بوده‌اند؛ یک یا دو بار با فاصله تکرار کنید یا مدل جایگزین بفرستید.
  • ۴۰۲: تکرار بی‌فایده است؛ به کاربر/مدیر هشدار شارژ بدهید (GET /me).
  • ۴۰۰/۴۰۴: درخواست را اصلاح کنید؛ تکرار همان درخواست همان خطا را می‌دهد.