أخطاء واجهات الذكاء الاصطناعي: اعرف السبب وطبّق الحل الصحيح

مرجع عملي لأخطاء OpenAI وAnthropic وGemini الشائعة، مرتب حسب سبب الخطأ والخطوة التي تعالجه، مع رابط التوثيق الرسمي.

بقلم فريق benchr · · كل خطأ متحقَّق منه مقابل التوثيق الرسمي للمزوّدين، 12 يونيو 2026

عرض 15 من أصل 15 خطأً

OpenAI · 429 · الحصةinsufficient_quota

لا يملك الحساب حصة قابلة للاستخدام؛ إعادة المحاولة لا تغيّر حالة الفوترة.

OpenAI · 429 · حد الاستخدامrate_limit_exceeded

تجاوز معدل الطلبات أو التوكنات الحد المتاح للحساب.

OpenAI · 400 · السياقcontext_length_exceeded

يتجاوز الإدخال مع حجم الإخراج المطلوب نافذة سياق النموذج.

OpenAI · 404 · التوفرmodel_not_found

معرّف خاطئ، نقطة وصول خاطئة، لا صلاحية — أو نموذج تقاعد في OpenAI.

OpenAI · 401 · المصادقةinvalid_api_key

"Incorrect API key provided" — المفتاح خاطئ أو مُلغى أو مشوّه.

Anthropic · 529 · الحِمل الزائدoverloaded_error

خدمة Anthropic محمّلة مؤقتاً؛ أعد المحاولة بتأخير عشوائي وحد زمني واضح.

Anthropic · 429 · حد الاستخدامrate_limit_error

سقف المستوى — أو حدود التسارع إذا تصاعد استخدامك بحدّة مفرطة.

Anthropic · 400 · الصيغةinvalid_request_error

افحص معاملات أخذ العينات غير المدعومة، والرد المعبأ مسبقاً، وكتل التفكير المعدّلة.

Anthropic · 413 · الحجمrequest_too_large

يتجاوز جسم الطلب حد 32 ميغابايت في واجهة Messages، فيُرفض قبل بدء المعالجة.

Anthropic · 404 · التوفرnot_found_error

منذ 15 يونيو 2026 صار السبب الأول معرّف نموذج Claude متقاعد.

Gemini · 429 · حد الاستخدامRESOURCE_EXHAUSTED

تجاوز المشروع أحد حدود الطلبات أو التوكنات أو الحصة في فئته الحالية.

Gemini · 400 · الصيغةINVALID_ARGUMENT

الطلب غير صالح، أو يستخدم ميزة لا يدعمها إصدار الواجهة.

Gemini · 404 · التوفرNOT_FOUND

مراجع ملفات منتهية — أو نموذج من سلسلة أوقفتها Google أصلاً.

Gemini · 504 · المهلةDEADLINE_EXCEEDED

لم يكتمل الطلب قبل انتهاء المهلة؛ قلّصه أو استخدم البث أو عدّل المهلة.

Gemini · 400 · الفوترةFAILED_PRECONDITION

الباقة المجانية غير متاحة في منطقة الخادم من دون تفعيل الفوترة.

الحصة وحدود الاستخدام: خطآن بالحالة 429

يستخدم OpenAI الحالة HTTP 429 لكل من تجاوز حد الاستخدام ونفاد الحصة أو الرصيد. يفيد الانتظار وإعادة المحاولة في الحالة الأولى، ولا يفيدان في الثانية. وقد تطلق Anthropic أيضاً حدود التسارع عند رفع الاستخدام بسرعة كبيرة حتى قبل بلوغ السقف المعلن. وإذا تكرر الخطأ، فقارن كلفة خفض الحمل أو توجيه المهام المناسبة إلى نموذج آخر عبر الحاسبة وترتيب النماذج.

النموذج غير موجود: افحص المعرّف وحالة التقاعد

تتقاعد عدة سلاسل من النماذج هذا العام: أُوقف Claude Sonnet 4 وOpus 4 في 15 يونيو، وتنتهي سلسلة Gemini 2.5 في 16 أكتوبر، ويتقاعد تسعة معرّفات من OpenAI في 23 أكتوبر. تربط صفحات أخطاء 404 لدى OpenAI وAnthropic وGemini إلى سجل الإيقافات الذي يعرض البدائل وفروق السعر. ويعرض المتتبّع الحالة الحالية لكل نموذج.

السياق أكبر من اللازم

يختلف تجاوز التوكنات (context_length_exceeded) عن تجاوز حجم الطلب بالبايتات (request_too_large). عالج الأول بحساب التوكنات وتقليص السياق، والثاني بقياس جسم الطلب ونقل المرفقات الكبيرة. وإذا كانت المهمة تحتاج سياقاً أطول، فراجع مقارنة نوافذ السياق.

مشكلات المصادقة والفوترة

عند ظهور خطأ 401، راجع المفتاح والمشروع والمؤسسة وترويسة المصادقة وقيود عناوين IP قبل تعديل منطق التطبيق. أما FAILED_PRECONDITION في Gemini فقد يشير إلى عدم توفر الخدمة في المنطقة أو إلى مشروع يحتاج إلى تفعيل الفوترة.

أخطاء الخادم والحِمل الزائد

يحتاج الخطأ 529 من Anthropic والخطأ 504 من Gemini عادةً إلى إعادة محاولة محدودة بمهلة، مع مراقبة واضحة، لا إلى إعادة كتابة التطبيق فوراً. وإذا كانت الاستمرارية مهمة، فاستخدم سجل الأسعار ومرجع النماذج لتسعير بديل واختباره قبل وقوع العطل.

سجل التغييرات

  • — أُطلِق القسم بـ 15 خطأً عبر OpenAI وAnthropic وGemini، كل منها متحقَّق منه مقابل التوثيق الرسمي للمزوّدين.

المصادر

  • OpenAI error codes guide — developers.openai.com/api/docs/guides/error-codes (تم التحقق في 12 يونيو 2026)
  • Anthropic API errors — platform.claude.com/docs/en/api/errors (تم التحقق في 12 يونيو 2026)
  • Gemini API troubleshooting — ai.google.dev/gemini-api/docs/troubleshooting (تم التحقق في 12 يونيو 2026)
  • benchr api-errors.json — مجموعة البيانات المهيكلة خلف هذا القسم

أسئلة شائعة

لماذا تظهر أخطاء API للذكاء الاصطناعي؟

تختلف الأسباب بين بلوغ حدود الاستخدام، ونفاد الحصة، وتجاوز السياق، وفشل المصادقة، وتقاعد النموذج، وضغط الخدمة. ابدأ برمز الحالة ونوع الخطأ، ثم راجع الصفحة الخاصة به بدلاً من تطبيق حل واحد على جميع الحالات.

هل تعتمد هذه الشروحات على مصادر رسمية؟

نعم. نراجع كل صفحة مقابل توثيق المزوّد: دليل أخطاء OpenAI، وصفحة أخطاء Anthropic، ودليل استكشاف أخطاء Gemini. ويظهر تاريخ التحقق على الصفحة، ونميّز اقتراحات benchr التحريرية عن تعليمات المزوّد.

ما الفرق بين حد استخدام 429 وinsufficient_quota؟

كلاهما يصل بحالة HTTP 429 من OpenAI، لكنهما يحتاجان استجابتين متعاكستين. حدود الاستخدام مؤقتة — تراجع وأعد المحاولة، فالحدود تُعاد كل دقيقة. أما insufficient_quota فيعني أن الفوترة استُنفدت — لا تصلحه أي إستراتيجية إعادة محاولة؛ يصلحه فقط إضافة رصيد أو رفع سقفك.