تنسيق استجابة الخطأ
تعيد جميع الأخطاء تنسيق JSON ثابتاً:رموز حالة HTTP
| الرمز | الوصف |
|---|---|
| 400 | Bad Request - معلمات غير صالحة |
| 401 | Unauthorized - مفتاح API غير صالح أو مفقود |
| 402 | Payment Required - رصيد غير كافٍ |
| 403 | Forbidden - تم رفض الوصول أو النموذج غير مسموح به |
| 404 | Not Found - النموذج أو المورد غير موجود |
| 413 | Payload Too Large - تم تجاوز حجم المدخلات أو الملف |
| 429 | Too Many Requests - تم تجاوز حد المعدل (Rate limit) |
| 500 | Internal Server Error |
| 502 | Bad Gateway - خطأ من المزود الرئيسي (Upstream) |
| 503 | Service Unavailable - فشلت جميع القنوات |
| 504 | Gateway Timeout - انتهت مهلة الطلب |
أنواع الأخطاء
أخطاء المصادقة (401)
| النوع | الرمز | الوصف |
|---|---|---|
invalid_api_key | invalid_api_key | مفتاح API مفقود أو غير صالح |
expired_api_key | expired_api_key | تم إلغاء مفتاح API |
أخطاء الدفع (402)
| النوع | الرمز | الوصف |
|---|---|---|
insufficient_quota | insufficient_quota | رصيد الحساب منخفض جداً |
quota_exceeded | quota_exceeded | تم الوصول إلى حد استخدام مفتاح API |
أخطاء الوصول (403)
| النوع | الرمز | الوصف |
|---|---|---|
access_denied | access_denied | تم رفض الوصول إلى المورد |
access_denied | model_not_allowed | النموذج غير مسموح به لمفتاح API هذا |
أخطاء التحقق من الصحة (400)
| النوع | الوصف |
|---|---|
invalid_request_error | معلمات الطلب غير صالحة |
context_length_exceeded | المدخلات طويلة جداً بالنسبة للنموذج |
model_not_found | النموذج المطلوب غير موجود |
أخطاء حد المعدل (429)
عندما تتجاوز حدود المعدل (rate limits):الحمولة كبيرة جداً (413)
عندما يتجاوز حجم المدخلات أو الملف الحدود المسموح بها:- ملف الصورة كبير جداً (بحد أقصى 20 ميجابايت)
- ملف الصوت كبير جداً (بحد أقصى 25 ميجابايت)
- نص المدخلات يتجاوز طول سياق (context length) النموذج
أخطاء المزود (502, 503)
| النوع | الوصف |
|---|---|
upstream_error | أعاد المزود خطأً |
all_channels_failed | لا يوجد مزودون متاحون |
timeout_error | انتهت مهلة الطلب |
معالجة الأخطاء في Python
معالجة الأخطاء في JavaScript
أفضل الممارسات
تنفيذ التراجع الأسي (Exponential backoff)
تنفيذ التراجع الأسي (Exponential backoff)
عند تقييد المعدل، انتظر لفترات أطول تدريجياً بين محاولات إعادة المحاولة:
تعيين مهلات زمنية (Timeouts)
تعيين مهلات زمنية (Timeouts)
قم دائماً بتعيين مهلات زمنية معقولة لتجنب الطلبات المعلقة:
تسجيل الأخطاء لتصحيح الأخطاء (Debugging)
تسجيل الأخطاء لتصحيح الأخطاء (Debugging)
قم بتسجيل استجابة الخطأ الكاملة بما في ذلك معرف الطلب (request ID) للدعم الفني:
معالجة الأخطاء الخاصة بالنموذج
معالجة الأخطاء الخاصة بالنموذج
بعض النماذج لها متطلبات محددة (مثل الحد الأقصى للرموز المميزة “tokens”، تنسيقات الصور).
تحقق من صحة المدخلات قبل إجراء الطلبات.