دليل تحديد المشاكل وحلّها

استخدِم هذا الدليل لمساعدتك في تشخيص المشاكل الشائعة التي تحدث عند استدعاء Gemini API وحلّها. قد تواجه مشاكل من خدمة الخلفية لواجهة Gemini API أو حِزم SDK للبرامج. حِزم تطوير البرامج (SDK) الخاصة بالعملاء مفتوحة المصدر في المستودعات التالية:

في حال مواجهة مشاكل في مفتاح واجهة برمجة التطبيقات، تأكَّد من إعداد مفتاح واجهة برمجة التطبيقات بشكل صحيح وفقًا لدليل إعداد مفتاح واجهة برمجة التطبيقات.

رموز الخطأ في خدمة الخلفية لواجهة Gemini API

يسرد الجدول التالي رموز الأخطاء الشائعة في الخلفية التي قد تواجهها، بالإضافة إلى توضيحات حول أسبابها وخطوات تحديد المشاكل وحلّها:

رمز HTTP الحالة الوصف مثال Solution
400 INVALID_ARGUMENT تمت صياغة نص الطلب بشكل غير صحيح. هناك خطأ إملائي أو حقل مطلوب ناقص في طلبك. راجِع مرجع واجهة برمجة التطبيقات لمعرفة تنسيق الطلب والأمثلة والإصدارات المتوافقة. قد يؤدي استخدام ميزات من إصدار أحدث من واجهة برمجة التطبيقات مع نقطة نهاية قديمة إلى حدوث أخطاء.
400 FAILED_PRECONDITION لا تتوفّر الطبقة المجانية من Gemini API في بلدك. يُرجى تفعيل الفوترة في مشروعك في Google AI Studio. أنت تقدّم طلبًا في منطقة لا تتوفّر فيها الطبقة المجانية، ولم تفعّل الفوترة في مشروعك على Google AI Studio. لاستخدام Gemini API، عليك إعداد خطة مدفوعة باستخدام Google AI Studio.
403 PERMISSION_DENIED لا يتضمّن مفتاح واجهة برمجة التطبيقات الأذونات المطلوبة. أنت تستخدم مفتاح API غير صحيح، أو تحاول استخدام نموذج معدَّل بدون إجراء المصادقة المناسبة. تأكَّد من ضبط مفتاح واجهة برمجة التطبيقات ومنحه إذن الوصول المناسب. وتأكَّد من إكمال عملية المصادقة بشكل صحيح لاستخدام النماذج المعدَّلة.
404 NOT_FOUND لم يتم العثور على المورد المطلوب. لم يتم العثور على ملف صورة أو صوت أو فيديو تمت الإشارة إليه في طلبك. تحقَّق مما إذا كانت جميع المَعلمات في طلبك صالحة لإصدار واجهة برمجة التطبيقات.
429 RESOURCE_EXHAUSTED تجاوزت أحد الحدود القصوى لمعدّل الطلبات في واجهة برمجة التطبيقات (طلبات في الدقيقة، وطلبات في الشهر، وطلبات في اليوم، والإنفاق، وما إلى ذلك). أنت ترسل عددًا كبيرًا جدًا من الطلبات أو تستخدم عددًا كبيرًا جدًا من الرموز المميزة أو تتجاوز الحدود المستندة إلى الإنفاق في سجلّ الفواتير والمستوى الخاصين بحسابك. تأكَّد من أنّك ضمن حدود المعدّل للنموذج. يُرجى الانتظار وإعادة المحاولة بعد فترة قصيرة. تقليل معدّل أو حجم الطلبات طلب زيادة الحدّ الأقصى لمعدّل الطلبات عند الحاجة
499 تم إلغاؤها تم إلغاء العملية، وعادةً ما يكون ذلك من قِبل المتصل. أغلق العميل الاتصال قبل أن تتمكّن واجهة برمجة التطبيقات من إنهاء الرد. تحقَّق ممّا إذا كان العميل أو البنية الأساسية للشبكة يغلقان الاتصال قبل الأوان (على سبيل المثال، بسبب انتهاء المهلة من جهة العميل).
500 للاستخدام الداخلي حدث خطأ غير متوقَّع من جهة Google. سياق الإدخال طويل جدًا. راجِع صفحة حالة Gemini API للاطّلاع على أي حوادث مستمرة. يمكنك تقليل سياق الإدخال أو التبديل مؤقتًا إلى نموذج آخر (مثل التبديل من Gemini 2.5 Pro إلى Gemini 2.5 Flash) لمعرفة ما إذا كان ذلك سيحلّ المشكلة. أو الانتظار قليلاً وإعادة محاولة إجراء الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio.
503 UNAVAILABLE قد تكون الخدمة محمّلة بشكل مؤقت أو معطّلة. نفدت سعة الخدمة مؤقتًا. راجِع صفحة حالة Gemini API للاطّلاع على أي حوادث مستمرة. بدِّل مؤقتًا إلى نموذج آخر (مثلاً من Gemini 2.5 Pro إلى Gemini 2.5 Flash) لمعرفة ما إذا كان ذلك سيحلّ المشكلة. أو الانتظار قليلاً وإعادة محاولة إجراء الطلب. إذا استمرت المشكلة بعد إعادة المحاولة، يُرجى الإبلاغ عنها باستخدام الزر إرسال ملاحظات في Google AI Studio.
504 DEADLINE_EXCEEDED يتعذّر على الخدمة إنهاء المعالجة في غضون الموعد النهائي.