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

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

رموز أخطاء HTTP

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

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

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