benchrخطأ في الطلب أم في إصدار الواجهة؟
تشترك حالتان في هذا الخطأ. الأولى هي وجود اسم حقل غير صحيح، أو حقل مطلوب مفقود، أو قيمة من نوع لا يقبله المخطط. قارن جسم الطلب بالمرجع الخاص بالإصدار الذي تستخدمه.
أما الحالة الثانية فهي إرسال طلب صالح إلى إصدار لا يدعم الميزة. تطرح Google بعض القدرات في v1beta قبل v1، لذلك قد لا يعمل مثال مأخوذ من صفحة توثيق مع نقطة الوصول المستخدمة في تطبيقك. ثبّت إصدار الواجهة صراحةً، وتأكد أن أمثلة SDK والمقتطفات التي تجمعها تستخدم الإصدار نفسه.
الاستجابة
جسم نموذجي، في قالب Google القياسي حيث يكرّر حقل code الرقمي حالة HTTP ويحمل status اسم gRPC:
{
"error": {
"code": 400,
"message": "The request body is malformed.",
"status": "INVALID_ARGUMENT"
}
}تختلف صياغة الرسالة حسب السبب، وقد لا تذكر الحقل المخالف. لذلك تكون إعادة بناء الطلب من نسخة صغيرة وصالحة أوضح من محاولة استنتاج السبب من نص الخطأ وحده.
ابدأ بأصغر طلب صالح
أثبت أن الأنابيب سليمة أولاً. أصغر استدعاء صالح لـ generateContent يضع النموذج في مسار الرابط ويرسل مُدخل contents واحداً:
curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent" \
-H "x-goog-api-key: $GEMINI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [
{ "parts": [ { "text": "Say hello." } ] }
]
}'إن نجح هذا، فقد انحرف مخططك في موضع أعلى منه: أعد حقولك الحقيقية واحداً تلو الآخر وسيظهر الخطأ 400 عند الإضافة بالضبط التي تكسره. وإن فشل حتى الاستدعاء الأدنى، فاشكُك في الرابط قبل الجسم — اسم النموذج ومقطع الإصدار يسببان من هذه الأخطاء أكثر مما تسببه أي حمولة.
ثبّت إصدار الواجهة
ضع إصدار API في الرابط صراحةً وعامله كإعداد، حتى تستخدم جميع البيئات نقطة الوصول نفسها. وتحقق من جسم الطلب مقابل مخطط قبل الإرسال؛ يمكن لفحص JSON Schema في CI أن يلتقط اسم الحقل الخاطئ قبل النشر.
عند الانتقال بين أجيال النماذج، راجع ملاحظات الإصدار ولا تفترض أن شكل الطلب لم يتغيّر. فقد تُضاف الحقول أو تُعاد تسميتها أو تتغيّر أنواعها. وإذا ظهر الخطأ بعد الانتقال إلى Gemini 3.1 Pro، فراجع المتتبّع وملاحظات الترحيل الخاصة بالنموذج.