Source: https://ailoot.ai/docs/ar/errors/
Canonical: https://ailoot.ai/docs/ar/errors/
Language: ar

[المساعدة](https://ailoot.ai/docs/ar/) 

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

[Markdown](https://ailoot.ai/docs/ar/errors/index.md)

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

## [](https://ailoot.ai/docs/ar/errors/#format)صيغة الخطأ

يأتي الخطأ بصيغة 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` — للعملاء الأقدم.

```json
{
  "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. …"
}
```

```json
{
  "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"
}
```

```json
{
  "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"
      }
    ]
  }
}
```

تعني “Nothing was charged” أنه لم يُخصم أي مبلغ. إذا تلقيت X-Should-Retry: false، فلا تُعد المحاولة تلقائياً؛ تحقق أولاً من Request ID في السجل.

## [](https://ailoot.ai/docs/ar/errors/#codes)رموز الأخطاء

| 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` بالقيم السابقة، فاستبدلها برموز الجدول؛ وسيبيّن مطابقة الرموز القديمة بالجديدة [الدعم](https://ailoot.ai/docs/ar/support/).

## [](https://ailoot.ai/docs/ar/errors/#retry)متى تعيد الطلب

- **تحقق أولاً من 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 — صحح الطلب أو المفتاح أو الرصيد أولاً.

تعيد حزم SDK من OpenAI وAnthropic عادةً الطلب تلقائياً عند أخطاء الشبكة و5xx. عطّل ذلك للتوليد (`max_retries=0`) وتحقق من `X-Should-Retry` قبل محاولة جديدة. فقدان الرد لا يعني أن الطلب لم يُنفَّذ.

## [](https://ailoot.ai/docs/ar/errors/#limits)الحدود

تُطبق حدود المعدل وعدد الطلبات المتزامنة على حسابك بأكمله، لا على كل مفتاح منفرد. عند تجاوزها، يأتي الرد 429 `rate_limit_exceeded` بالترويسة `Retry-After: 10`. إذا كان النموذج نفسه مثقلاً، يأتي الرد 503 `model_overloaded` مع `Retry-After: 30`. إذا احتجت إلى حمل أكبر، فتواصل مع [الدعم](https://ailoot.ai/docs/ar/support/).

تُحدد حدود الإنفاق لكل مفتاح: الحد الإجمالي — 402 `api_key_quota_exhausted`، ونوافذ 5 ساعات ويوم واحد و7 أيام — 429 `usage_limit_reached`. مزيد من التفاصيل — [المفاتيح وعنوان API](https://ailoot.ai/docs/ar/keys/#key).

## [](https://ailoot.ai/docs/ar/errors/#nvidia)نماذج NVIDIA: قائمة الانتظار

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

يحدد النموذج حدود الحجم: السياق (عدد التوكنات التي يمكن إرسالها) وأقصى طول للرد. وهي موضحة في [الكتالوج](https://ailoot.ai/models/ar/).

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

[السجل والتكاليف](https://ailoot.ai/usage) · [GET https://ailoot.ai/api/v1/usage](https://ailoot.ai/docs/ar/cabinet/usage/) · JWT · `Authorization: Bearer $TOKEN`

`JWT ≠ sk-…` · [تسجيل الدخول والجلسات](https://ailoot.ai/docs/ar/cabinet/auth/)

هل لديك أسئلة أخرى؟ أرسل Request ID ووصفاً للمشكلة وسنساعدك على فهمها.[مراسلة الدعم](mailto:support@ailoot.ai)

## Ailoot · الشركة ومحفظة مشاريعها





تستند Ailoot إلى خبرة تشغيلية متراكمة وقاعدة عملاء واسعة وخدمة مستقرة ومراقبة مستمرة لمؤشرات الأداء KPI.





الشركة ومحفظة مشاريعها: ملايين العملاء؛ مبيعات بالمليارات شهريًا.





توظف Ailoot هذه الخبرة التشغيلية لإتاحة الوصول عبر API إلى قدرات الذكاء الاصطناعي في منتجات العملاء ووكلائهم وتطبيقاتهم وعمليات الأتمتة.