Developer guide
رمز الخطأ
الإجراءات وقواعد إعادة المحاولة حسب رمز الحالة
تُلخّص هذه الصفحة رموز الحالة التي يعيدها البوابة ومعانيها والإجراءات الخاصة بكل رمز.
إذا أعاد مزوّد الخدمة العلوي رمز 4xx أو 5xx، فسيتم تمرير الرمز كما هو، وفي الحالات الأخرى يُتّبع الجدول أدناه.
كما يوضّح الشكلَين الأساسيين لنص الخطأ في المواصفتين المتوافقتين، وقواعد error.type المتوافق مع Anthropic، وشاشة وحدة التحكم للتحقق من الحدود والاستخدام.
رمز الحالة
| الرمز | المعنى | الإجراء |
|---|---|---|
| 400 | خطأ في قيمة الطلب. قيمة limit في قائمة نماذج Anthropic المتوافقة خارج النطاق من 1 إلى 1000، أو تمت محاولة استئناف استجابة محفوظة باستخدام GET /responses/{responseId}?stream=true | صحّح القيمة لتكون ضمن النطاق. استعلم عن الاستجابة المحفوظة من دون stream. |
| 401 | مفتاح مفقود أو منتهي الصلاحية أو مُلغى | تحقق من حالة المفتاح في صفحة مفاتيح API، وافحص اسم الترويسة وبادئة Bearer. |
| 403 | لا يوجد إذن للوصول إلى النموذج، أو تم تجاوز حد الاستخدام، أو لا توجد أرصدة كافية، أو لست مالك الصوت | توضّح error.message السبب. ويمكن الاطلاع على القيم في شاشات قسم التحقق من الحدود والاستخدام أدناه. |
| 404 | النموذج غير موجود أو لا يمكن الوصول إليه باستخدام هذا المفتاح (بما في ذلك النماذج التي انتهى دعمها)، أو المسار غير موجود، أو مخرجات CleviDrive التي تجاوزت فترة الاحتفاظ البالغة 3 أيام | تحقق أولًا من قائمة النماذج التي يمكن استدعاؤها باستخدام GET /models. وقارن المسار بالجدول الموجود في صفحة إجراء استدعاءات API. |
| 408 · 409 · 413 | انتهاء مهلة مزوّد الخدمة العلوي، أو الازدحام، أو تجاوز حجم الطلب. الحد الزمني لمسارات الصوت والصوتيات هو 5 دقائق، والحد الأقصى للطلب هو 28 MiB | إذا وُجد Retry-After في 409، فانتظر تلك المدة. وبالنسبة إلى 413، قسّم الطلب وأرسله على أجزاء. |
| 429 | عندما يفرض مزوّد الخدمة العلوي تحديدًا لمعدل الطلبات | إذا ظهر Retry-After، فاتّبعه كما هو، وإذا لم يظهر فأعد المحاولة باستخدام التراجع الأُسّي. |
| 5xx | خطأ مؤقت في البوابة أو مزوّد الخدمة العلوي (بما في ذلك 503) | أعد المحاولة باستخدام التراجع الأُسّي. وإذا تكرر الخطأ، فأبلغنا عبر المساعدة والتواصل، مع X-Request-Id. |
إعادة المحاولة
لا تنشئ البوابة رمز 429 خاصًا بها، ولا تعيد محاولة استجابة مزوّد الخدمة العلوي خفيةً أو تضعها في قائمة انتظار.
يتولى العميل الانتظار وإعادة المحاولة.
| الكود | وقت الانتظار | بعد ذلك |
|---|---|---|
| 409 | إذا وُجد Retry-After، فانتظر تلك المدة | أرسل الطلب نفسه مرة أخرى. |
| 429 | إذا وُجد Retry-After، فانتظر تلك المدة؛ وإلا فاستخدم التراجع الأُسّي | أرسل الطلب نفسه مرة أخرى. |
| 5xx | التراجع الأُسّي | إذا تكرر الأمر، فتواصل معنا. |
| 413 | لا انتظار | قسّم الطلب. |
نص الخطأ
يختلف شكل نص الخطأ حسب المواصفة. نحتفظ برسالة أخطاء الخدمة الأصلية فقط وننقلها بعد تنسيقها، ولا يتم تمرير التتبعات أو الحقول الداخلية.
هذا هو نص مسار التوافق مع OpenAI.
{
"error": {
"message": "API key is required.",
"type": "invalid_request_error"
}
}هذا هو نص مسار التوافق مع Anthropic. يتم تحديد error.type وفقًا لرمز الحالة.
{
"type": "error",
"error": {
"type": "authentication_error",
"message": "..."
},
"request_id": "rqid..."
}| رمز الحالة | error.type |
|---|---|
| 400 | invalid_request_error |
| 401 | authentication_error |
| 403 | permission_error |
| 404 | not_found_error |
| 413 | request_too_large |
| 429 | rate_limit_error |
| 529 | overloaded_error |
| الرموز الأخرى | api_error |
التحقق من الحدود والاستخدام
تختلف أرقام الحدود من مساحة عمل إلى أخرى. تحقّق من سبب 403 في error.message، ثم راجع الأرقام في الشاشة أدناه.
| ما يجب التحقق منه | شاشة وحدة التحكم |
|---|---|
| الحد المفروض على مساحة عملي | حد الاستخدام المخصص في النظرة العامة |
| النطاق والرصيد اللذان تسمح بهما الخطة | الخطة والائتمانات |
| الاستخدام الفعلي (عدد الاستدعاءات حسب النموذج والمفتاح، والائتمانات المتوقع خصمها) | الاستخدام |
| حالة المفتاح (ما إذا كان منتهي الصلاحية أو ملغى) | مفاتيح API |