أخطاء API للذكاء الاصطناعي: جدها، أصلِحها، اختر نموذجاً أفضل

أخطاء شائعة عبر OpenAI وAnthropic وGemini — متحقَّق منها مقابل التوثيق الرسمي، مع الحل وبيانات النماذج للالتفاف حول المشكلة.

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

عرض 15 من 15 خطأً

OpenAI · 429 · الحصةinsufficient_quota

"You exceeded your current quota" — الفوترة فارغة؛ إعادة المحاولة لا تصلحها.

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

بلغت سقف RPM أو TPM. مؤقت — الحدود تُعاد كل دقيقة.

OpenAI · 400 · السياقcontext_length_exceeded

الموجّه زائداً max_tokens تجاوزا نافذة النموذج.

OpenAI · 404 · التوفرmodel_not_found

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

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

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

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

ضغط على مستوى المنصة كلها، لا على حسابك. تراجع وانتظر زواله.

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

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

Anthropic · 400 · الصيغةinvalid_request_error

في 2026: معاملات المعاينة على Opus 4.7+، أو الـ prefill، أو كتل تفكير معدَّلة.

Anthropic · 413 · الحجمrequest_too_large

جسم الطلب فوق سقف 32 MB لواجهة Messages — مرفوض قبل أن تراه Anthropic.

Anthropic · 404 · التوفرnot_found_error

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

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

خطأ الطبقة المجانية المميَّز: طلبات في الدقيقة أكثر مما يسمح به مستواك.

Gemini · 400 · الصيغةINVALID_ARGUMENT

جسم مشوّه — أو ميزة لا وجود لها في إصدار API لديك.

Gemini · 404 · التوفرNOT_FOUND

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

Gemini · 504 · المهلةDEADLINE_EXCEEDED

موجّهات ضخمة تجاوزت الساعة. استخدم البث، أو قلّص، أو ارفع المهلة.

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

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

الحصة وحدود الاستخدام: الـ 429 اللذان يحتاجان حلَّين متعاكسين

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

النموذج غير موجود: أسرع خطأ نمواً في 2026

ثلاثة مزوّدين يقاعدون سلاسل نماذج هذا العام — أُظلمت Claude Sonnet 4 وOpus 4 في 15 يونيو، وتنتهي سلسلة Gemini 2.5 في 16 أكتوبر، ويقاعد OpenAI تسعة معرّفات في 23 أكتوبر. كل 404 في هذه الفئة (OpenAI، Anthropic، Gemini) يربط بـسجل الإيقافات، حيث يحمل كل تقاعد بديله وحساب السعر قبل وبعد. ويُظهر المتعقّب الحي الحالة الراهنة لكل نموذج.

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

تجاوز التوكنز (context_length_exceeded) وتجاوز البايتات (request_too_large) يفشلان بطريقتين مختلفتين ويحتاجان حلَّين مختلفين — عدّ التوكنز مقابل قياس الحمولة. حين لا يكون التقليص خياراً، فالحل نافذة أوسع: مقارنة نوافذ السياق تُظهر ما تساويه فعلاً نافذة كل نموذج المعلنة في الواقع.

جدران المصادقة والفوترة

إخفاقات المصادقة (أخطاء 401) أرخص الأخطاء منعاً وأكثرها إحراجاً عند تصحيحها منتصف الليل. وأما 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 للذكاء الاصطناعي في 2026؟

بسبب تقاعد النماذج. توقف OpenAI تسعة معرّفات نماذج في 23 أكتوبر 2026، وتقاعدت Claude Sonnet 4 وOpus 4 من Anthropic في 15 يونيو، وتنتهي سلسلة Gemini 2.5 من Google في 16 أكتوبر. الكود المثبَّت على معرّفات قديمة يبدأ بإرجاع 404 — ولهذا كل خطأ توفّر نموذج هنا يربط مباشرة بسجل الإيقافات في benchr.

هل شروحات الأخطاء هذه رسمية؟

كل صفحة متحقَّق منها مقابل توثيق الأخطاء الخاص بالمزوّد نفسه — دليل أكواد أخطاء OpenAI، وصفحة أخطاء API من Anthropic، وتوثيق استكشاف أخطاء Gemini من Google — مع طباعة تاريخ التحقق على الصفحة. وحيث يضيف benchr نصيحة تحريرية (مثل نماذج بديلة أرخص)، تُوسَم بأنها اختيار benchr.

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

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