الأخطاء والحدود

رموز الردود ومعانيها والإجراءات المطلوبة. جميع الأخطاء بصيغة JSON ومع Request ID.

الدليل الكامل

صيغة الخطأ

يأتي الخطأ بصيغة API التي استدعيتها: الكائن error لـOpenAI، و {"type": "error", "error": {...}} لـAnthropic، و error بالحقول status و details لـGemini. لذلك تتعرف حزم SDK عليها كأخطاء API عادية.

error.code و error.reason — فئة الخطأ من الجدول أدناه، وهما متطابقان. error.type — القيمة القياسية للصيغة (مثل invalid_request_error أو server_error).
error.request_id (في Anthropic يكون request_id في المستوى الأعلى)، والترويسة X-Request-ID ونهاية نص الرسالة — معرّف الطلب.
في Gemini توجد الفئة في error.details: ErrorInfo.reason — الرمز نفسه بالأحرف الكبيرة (مثل MODEL_OVERLOADED), domain — ailoot.ai؛ ويوجد معرّف الطلب في RequestInfo.requestId.
في صيغة Gemini، يأتي خطأ 5xx الذي لا يجوز تكراره تلقائياً، وكذلك result_pending_check بحالة 409 و status ABORTED، كي لا يعيد Gemini SDK وCLI الطلب تلقائياً. توجد فئة الخطأ في ErrorInfo.reason (مثل MODEL_TIMEOUT أو RESULT_PENDING_CHECK).
يتضمن الرد بصيغة OpenAI أيضاً حقلي المستوى الأعلى code و message — للعملاء الأقدم.

{
  "code": "API_KEY_REQUIRED",
  "error": {
    "code": "invalid_api_key",
    "message": "No API key was sent with the request. Nothing was charged. Please check that the full key is sent in the Authorization header as \"Bearer <key>\". Request ID: 3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6.",
    "param": null,
    "reason": "invalid_api_key",
    "request_id": "3b28d3de-5b02-4d07-9f3c-4b9a7d0e68d6",
    "type": "invalid_request_error"
  },
  "message": "No API key was sent with the request. Nothing was charged. …"
}

{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "reason": "invalid_api_key",
    "message": "… Nothing was charged. … Request ID: 94ed3e31-4373-41ce-bf8a-0d1ed3f7235e."
  },
  "request_id": "94ed3e31-4373-41ce-bf8a-0d1ed3f7235e"
}

{
  "error": {
    "code": 401,
    "status": "UNAUTHENTICATED",
    "message": "The API key is not valid. Nothing was charged. … Request ID: e7aa743b-9d0d-4064-b206-2562609f545b.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_API_KEY",
        "domain": "ailoot.ai",
        "metadata": {
          "code": "invalid_api_key",
          "reason": "invalid_api_key",
          "request_id": "e7aa743b-9d0d-4064-b206-2562609f545b"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "e7aa743b-9d0d-4064-b206-2562609f545b"
      }
    ]
  }
}

رموز الأخطاء

HTTP	الفئة (reason)	ما الذي حدث	الإجراء المطلوب
400	`invalid_request`	الطلب غير صالح: جسم أو معامل غير صحيح؛ أو النموذج لا يدعم حقلاً أو مرفقاً أو أداة في الطلب؛ أو أُرسل المفتاح في العنوان	صحح الطلب وفق نص الخطأ: احذف الحقل أو المرفق أو الأداة غير المدعومة، وأرسل المفتاح في الترويسة. يحدث الرفض لعدم دعم حقل أو مرفق أو أداة قبل الحجز، دون خصم أي مبلغ
400	`context_length_exceeded`	يتجاوز الطلب نافذة سياق النموذج	اختصر السجل أو اختر نموذجاً بسياق أكبر
400	`content_policy_violation`	رُفض الطلب بسبب قواعد النموذج	أعد صياغة الطلب
401	`invalid_api_key`	المفتاح مفقود أو غير صحيح	تحقق من إرسال المفتاح كاملاً
401	`api_key_disabled`	المفتاح معطّل	فعّل المفتاح أو أنشئ مفتاحاً جديداً
402	`insufficient_balance`, `insufficient_quota`	الرصيد المتاح غير كافٍ حتى للحد الأدنى من الحجز (`insufficient_quota` — الحالة نفسها بصيغة مألوفة لـOpenAI SDK)	اشحن الرصيد أو اخفض max_tokens
402	`api_key_quota_exhausted`	استُنفد الحد الإجمالي لإنفاق المفتاح	ارفع حد المفتاح في لوحة الحساب
402	`payment_disputed`	على الحساب دين بسبب دفعة محل اعتراض	تُوقف الطلبات الجديدة حتى التسديد؛ تواصل مع الدعم
403	`api_key_expired`	انتهت صلاحية المفتاح	أنشئ مفتاحاً جديداً
403	`account_inactive`	حسابك معطّل	تواصل مع الدعم
403	`permission_denied`	لا يسمح المفتاح بهذا الطلب (مثلاً بسبب IP)	تحقق من قيود المفتاح
404	`model_not_found`	لا يوجد هذا النموذج	طابق ID مع /v1/models
404	`unsupported_endpoint`	لا يعمل النموذج بهذه الصيغة	اختر صيغة أو نموذجاً آخر
404	`not_found`	لا يوجد هذا المسار أو الكائن (مثل المهمة)	تحقق من العنوان والمعرّف
409	`duplicate_request`	قُبلت بالفعل عملية بالمفتاح نفسه لعدم التكرار، وربما اكتملت	تحقق من نتيجة العملية الأولى ولا ترسل عملية جديدة
409	`not_ready`, `video_not_ready`	الفيديو أو المهمة الأخرى غير جاهزة بعد	استعلم عن الحالة لاحقاً
409, 503	`result_pending_check`	نتحقق من نتيجة الطلب. في مهمة الفيديو يكون ذلك بالعلامة `result_pending_check: true` في رد الحالة، وتبقى المهمة نفسها `in_progress`	لا تُعد إرسال الطلب؛ ستظهر الحالة في السجل (GET https://ailoot.ai/api/v1/usage). لا تنشئ مهمة الفيديو مجدداً؛ تحقق منها لاحقاً عبر GET /v1/videos/{id}
410	`model_retired`	أُوقف النموذج عن الخدمة	اختر إصداراً جديداً من GET /v1/models
413	`request_too_large`	جسم الطلب كبير جداً	قلل حجم الملفات أو السجل
429	`rate_limit_exceeded`, `gateway_concurrency_limit`, `gateway_queue_full`	عدد الطلبات أو الطلبات المتزامنة من حسابك كبير جداً	انتظر (الترويسة `Retry-After`، عادةً 10 ثوانٍ) ثم أعد المحاولة
429	`usage_limit_reached`	استُنفدت نافذة إنفاق المفتاح (5 ساعات أو يوم واحد أو7 أيام)	انتظر تحديث النافذة أو ارفع حد المفتاح
500	`internal_error`	خطأ في Ailoot	تواصل مع الدعم مع إرفاق Request ID
502	`invalid_model_response`, `empty_response`, `incomplete_response`	أعاد النموذج رداً غير صالح أو فارغاً أو غير مكتمل	ابحث عن Request ID في سجل لوحة الحساب. إذا وُجدت نتيجة أو عملية خصم، فستنشئ الإعادة طلبًا مدفوعًا ثانيًا. عدم وجود سجل لا يؤكد أن الطلب لم يُرسل أو لم يُنفَّذ: لا تُعِد إرسال طلب مجهول الحالة؛ تواصل مع الدعم وأرفق Request ID.
502	`result_not_delivered`	لم تُسلّم النتيجة بسبب خطأ من Ailoot، وأُعيد المبلغ المحجوز أو المخصوم	يمكن إرسال الطلب مجدداً
503	`model_overloaded`	النموذج مثقل مؤقتاً	إذا كانت X-Should-Retry: true، فأعد المحاولة بعد عدد الثواني في Retry-After؛ وإذا كانت false، فتحقق أولاً من Request ID في السجل
503	`model_unavailable`	النموذج غير متاح مؤقتاً	اختر نموذجاً آخر. إذا كانت X-Should-Retry: true، فأعد المحاولة بعد عدد الثواني في Retry-After؛ وإذا كانت false، فتحقق أولاً من Request ID في السجل
503	`service_unavailable`	عطل مؤقت من جهة Ailoot	إذا كانت X-Should-Retry: true، فأعد المحاولة بعد عدد الثواني في Retry-After؛ وإذا كانت false، فتحقق أولاً من Request ID في السجل
503	`charge_not_confirmed`	لم يُقدّم الرد: تعذر تأكيد الخصم؛ أُعيد المبلغ المحجوز ولم يُخصم أي مبلغ	إذا كانت X-Should-Retry: true، فأعد المحاولة بعد عدد الثواني في Retry-After؛ وإذا كانت false، فتحقق أولاً من Request ID في السجل
504	`model_timeout`	لم يرد النموذج في الوقت المحدد، وقد تظهر النتيجة لاحقاً	لا تُعد إرسال الطلب حتى تتحقق من Request ID في السجل

أصبحت رموز ردود النموذج والتحقق من النتيجة (502 و503 و504) تشير إلى النموذج أو الطلب: model_unavailable, model_timeout, invalid_model_response, incomplete_response, charge_not_confirmed و result_pending_check. إذا كان الكود يقارن error.code بالقيم السابقة، فاستبدلها برموز الجدول؛ وسيبيّن مطابقة الرموز القديمة بالجديدة الدعم.

متى تعيد الطلب

تحقق أولاً من X-Should-Retry: عند false, result_pending_check أو model_timeout لا تُعد المحاولة تلقائياً. ابحث عن Request ID في سجل لوحة الحساب، حيث تظهر النتيجة والخصم.
تكون إعادة المحاولة آمنة عندما تتلقى X-Should-Retry: true: انتظر Retry-After ثانية. لا يكفي رمز 5xx وحده: فقد تكون النتيجة ظهرت بالفعل. تحقق أولاً من السجل في لوحة الحساب أو تواصل مع الدعم مع إرفاق Request ID. يهم ذلك خصوصاً للصور والفيديو والموسيقى وخطوات الوكلاء الطويلة.
إعادة المحاولة لن تفيد: 400, 401, 402, 403, 404 — صحح الطلب أو المفتاح أو الرصيد أولاً.

الحدود

تُطبق حدود المعدل وعدد الطلبات المتزامنة على حسابك بأكمله، لا على كل مفتاح منفرد. عند تجاوزها، يأتي الرد 429 rate_limit_exceeded بالترويسة Retry-After: 10. إذا كان النموذج نفسه مثقلاً، يأتي الرد 503 model_overloaded مع Retry-After: 30. إذا احتجت إلى حمل أكبر، فتواصل مع الدعم.

تُحدد حدود الإنفاق لكل مفتاح: الحد الإجمالي — 402 api_key_quota_exhausted، ونوافذ 5 ساعات ويوم واحد و7 أيام — 429 usage_limit_reached. مزيد من التفاصيل — المفاتيح وعنوان API.

نماذج NVIDIA: قائمة الانتظار

يمكن طلب قائمة النماذج حتى برصيد صفري، لكن التوليد يحتاج إلى رصيد للحجز. تعمل نماذج NVIDIA (Nemotron وغيرها) عبر قائمة انتظار مشتركة: قد يتأخر الرد عند الحمل العالي أو يأتي خطأ «النموذج مثقل مؤقتاً» مع ترويسة Retry-After؛ أعد المحاولة بعد المدة المحددة. الأسعار في الكتالوج، والخصم كما في النماذج الأخرى.

يحدد النموذج حدود الحجم: السياق (عدد التوكنات التي يمكن إرسالها) وأقصى طول للرد. وهي موضحة في الكتالوج.

السجل والتكاليف

السجل والتكاليف · GET https://ailoot.ai/api/v1/usage · JWT · Authorization: Bearer $TOKEN

JWT ≠ sk-… · تسجيل الدخول والجلسات

هل لديك أسئلة أخرى؟ أرسل Request ID ووصفاً للمشكلة وسنساعدك على فهمها.مراسلة الدعم