الأخطاء

غلاف الخطأ

{
  "error": {
    "message": "Human-readable description of what went wrong",
    "type": "invalid_request_error"
  }
}

هذا هو نفس الغلاف الذي تستخدمه واجهة OpenAI نفسها، لذا فإن معالجة الأخطاء المكتوبة ضد عميل متوافق مع OpenAI موجود أصلاً يجب أن تستمر في العمل دون تغييرات: تحقق من رمز حالة HTTP أولاً، واقرأ error.message للحصول على رسالة تستحق عرضها لمطور أو تسجيلها. أما error.type فهو فئة ثابتة قابلة للفحص آليًا، مفيدة لمنطق التفريع (إعادة المحاولة أو عدمها، طلب مفتاح API جديد أو التراجع والمحاولة مرة أخرى) دون تحليل الرسالة النصية الحرة.

رموز الحالة والأنواع

الحالة	النوع	المعنى
400	invalid_request_error	الطلب نفسه مشوَّه: model غير معروف، أو مصفوفة messages مفقودة أو فارغة، أو رسالة بدور غير مدعوم، أو تعريف tools مشوَّه. أصلح الطلب؛ إعادة المحاولة دون تغيير أي شيء ستفشل بنفس الطريقة في كل مرة.
401	authentication_error	ترويسة Authorization مفقودة، أو مشوَّهة، أو المفتاح غير صالح، أو منتهي الصلاحية، أو مُلغى. راجع المصادقة.
429	rate_limit_error	طلبات كثيرة جدًا في نافذة زمنية قصيرة على هذا المفتاح. راجع حدود المعدل لمعرفة الحد وكيفية التراجع بشكل صحيح.
500	api_error	خطأ غير متوقع من جانب الخادم لا علاقة له بطلبك. نادر؛ يمكن إعادة المحاولة بأمان، ويفضَّل مع تراجع قصير.
503	api_error	الخدمة غير قادرة مؤقتًا على إكمال الطلب، وعادةً ما تكون مشكلة عابرة في البنية التحتية للتوليد الخاصة بـ tAI نفسها لا خطأ في طلبك. يمكن إعادة المحاولة بأمان.

بضعة أمثلة

نموذج غير معروف:

HTTP/1.1 400 Bad Request

{"error": {"message": "Unknown model: 'tai-4.9'. See https://docs.artfical.com/tai/en for the current list.", "type": "invalid_request_error"}}

مفتاح غير صالح أو منتهي الصلاحية:

HTTP/1.1 401 Unauthorized

{"error": {"message": "Invalid API key.", "type": "authentication_error"}}

مشكلة عابرة في الخدمة:

HTTP/1.1 503 Service Unavailable

{"error": {"message": "The AI service is temporarily unavailable. Please retry.", "type": "api_error"}}

الأخطاء في منتصف البث

بمجرد أن تبدأ استجابة متدفقة (الاتصال مفتوح والقطع بدأت بالوصول)، لم يعد بالإمكان الإبلاغ عن خطأ كجسم JSON عادي للخطأ برمز حالة خارج نطاق 2xx، لأن رمز حالة HTTP والترويسات أُرسلت بالفعل كـ 200 عند بداية البث. بدلاً من ذلك، يظهر الفشل الذي يحدث في منتصف البث كقطعة محتوى مرئية (عادةً إشعار قصير بين قوسين) تليها قطعة إنهاء عادية ثم [DONE]، بدلاً من انقطاع الاتصال ببساطة. راجع البث لمعرفة الشكل الدقيق ولماذا يُضمَن أن ينتهي البث بشكل نظيف في الحالتين.

ما يستحق إعادة المحاولة

كقاعدة عامة: أخطاء 400 و401 تصف خللاً في الطلب نفسه أو في المفتاح نفسه، وإعادة المحاولة بشكل مطابق ستفشل بشكل مطابق في كل مرة، لذا أصلح المشكلة الأساسية أولاً. أما 429 و500 و503 فكلها آمنة لإعادة المحاولة، ويفضَّل مع تأخير قصير وحد أقصى لعدد المحاولات الإجمالي بدلاً من إعادة المحاولة في حلقة ضيقة؛ راجع حدود المعدل تحديدًا لمعرفة كيفية التراجع الصحيح عن خطأ 429.