أخطاء واجهة برمجة التطبيقات

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

رموز أخطاء HTTP

يسرد الجدول التالي رموز الخطأ الشائعة في الخلفية وتفسيرات لأسبابها والحلول المقترَحة:

رمز HTTP الحالة الوصف مثال Solution
400 INVALID_ARGUMENT تمت صياغة نص الطلب بشكل غير صحيح. هناك خطأ إملائي أو حقل مطلوب ناقص في طلبك. راجِع مرجع واجهة برمجة التطبيقات لمعرفة تنسيق الطلب والأمثلة والإصدارات المتوافقة. قد يؤدي استخدام ميزات من إصدار أحدث من واجهة برمجة التطبيقات مع نقطة نهاية قديمة إلى حدوث أخطاء.
400 FAILED_PRECONDITION لا تتوفّر الطبقة المجانية من Gemini API في بلدك. يُرجى تفعيل الفوترة في مشروعك في Google AI Studio. أنت بصدد تقديم طلب في منطقة لا تتوفّر فيها الطبقة المجانية، ولم تفعّل الفوترة في مشروعك على Google AI Studio. لاستخدام Gemini API، عليك إعداد خطة مدفوعة باستخدام Google AI Studio.
402 RESOURCE_EXHAUSTED تم استنفاد رصيد الدفع المُسبَق. نفدت أرصدة الدفع المُسبَق من حساب الفوترة، لذا سيتوقّف كل مفتاح واجهة برمجة تطبيقات مرتبط بحساب الفوترة هذا عن العمل. أضِف رصيدًا إلى حساب الفوترة أو فعِّل ميزة تعبئة الرصيد تلقائيًا. لا تعِد محاولة إرسال هذا الطلب: لن ينجح إلا بعد إضافة رصيد.
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 يتعذّر على الخدمة إنهاء المعالجة في غضون الموعد النهائي. طلبك (أو سياقك) كبير جدًا بحيث لا يمكن معالجته في الوقت المناسب. اضبط قيمة "مهلة" أكبر في طلب العميل لتجنُّب هذا الخطأ.

تنسيق ردّ الخطأ

عندما يتعذّر تنفيذ طلب GenerateContent، تضبط واجهة برمجة التطبيقات رمز حالة HTTP (مثل 400 Bad Request أو 403 Forbidden أو 429 Too Many Requests) وتعرض نص استجابة JSON يتضمّن تفاصيل حالة gRPC:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
الحقل النوع الوصف
code عدد صحيح رمز حالة HTTP
message سلسلة وصف للخطأ يمكن للمستخدمين قراءته
status سلسلة رمز حالة gRPC في SCREAMING_CASE
details صفيف سياق الخطأ الإضافي، مثل ErrorInfo أو LocalizedMessage

الخطوات التالية