خطأ Gemini ‏FAILED_PRECONDITION: المعنى والسبب والحل

الخطأ الذي لا يظهر إلا بعد النشر. كودك لم يتغيّر بين حاسبك والخادم — تغيّر عنوانه.

بقلم فريق benchr · · تم التحقق من توثيق Google لاستكشاف أخطاء Gemini API في 12 يونيو 2026

Google GeminiHTTP 400الخطورة: عاليةالحصة والفوترة

جدار منطقة، لا خلل كود

النمط ثابت إلى حدّ يستحق اسماً: كل شيء يمرّ على حاسبك، ثم أول طلب من VPS جديد أو صندوق سحابي يموت بخطأ 400. توفّر الباقة المجانية يعتمد على البلد الذي يأتي منه الطلب، ومركز بيانات في فرانكفورت أو سنغافورة ليس المكتب الذي اختبرت عنده. ترفض واجهة API الاستدعاء قبل معالجة توكن واحد؛ فحص الشرط المسبق يعمل أولاً. تفعيل الفوترة يُزيل الجدار، لأن الباقة المدفوعة لا تحمل قيود الباقة المجانية المناطقية.

كيف يبدو

جسم استجابة نموذجي، في قالب Google القياسي حيث يعكس حقل code الرقمي حالة HTTP ويحمل status اسم gRPC:

{
  "error": {
    "code": 400,
    "message": "User location is not supported for the API use without a billing account linked.",
    "status": "FAILED_PRECONDITION"
  }
}

الصياغة تختلف حسب الإعداد، لذا اربط معالجتك بسلسلة status، لا بالجملة.

ثلاثة فحوص، بالترتيب

أولاً: أين يعمل الخادم؟ ليس حيث اشتريته، بل حيث يجلس مركز البيانات. لوحات الاستضافة تدفن هذا؛ إعداد المنطقة لدى مزوّدك هو الحقيقة. ثانياً: هل الفوترة مربوطة؟ افتح المشروع في Google AI Studio وتحقّق، لا تفترض. ثالثاً: هل المفتاح من المشروع الذي تظنّه؟ متغيرات البيئة القديمة تشير إلى مشاريع تجريبية غير مفوترة أكثر ممّا يعترف أحد، والإصلاح الذي طبّقته على المشروع الصحيح لا يفعل شيئاً للمفتاح الخاطئ.

بعد الفوترة: ضع ميزانية كشخص راشد

ما إن تُفعَّل الفوترة، تعود الباقة المجانية إلى عملها الحقيقي — الاختبار، لا حركة الإنتاج. اضبط تنبيهات الميزانية في اليوم نفسه، بحجم رقم يجعلك تنظر مرتين. ثم سعّر الحِمل بصدق: Gemini 3.5 Flash بسعر 1.50$ للإدخال و9.00$ للإخراج لكل مليون توكن يُبقي المنتجات المتواضعة في حدود الفكّة، ومعرفة هذا الرقم خير من الخوف منه. وإن كان مشروعك يستحق فعلاً ميزانية صفرية، فإن دليل بلا اشتراك يغطّي مَن يستطيع البقاء مجاناً دون الاصطدام بجدران كهذا.

أسئلة شائعة

لماذا يعمل كودي محلياً ولا يعمل على خادمي؟

تفحص واجهة API من أين يأتي الطلب. حاسبك يجلس في بلد تغطّيه الباقة المجانية؛ ومركز بيانات خادمك يجلس في بلد يطلب حساب فوترة أولاً. الكود نفسه، عنوان مختلف.

هل مفتاح API لديّ معطّل؟

لا. FAILED_PRECONDITION فشل في شرط مسبق، لا في المصادقة. مفتاح بصلاحيات ناقصة يُرجع PERMISSION_DENIED (403) بدلاً منه. مفتاحك سليم؛ المشروع خلفه يحتاج فوترة.

هل تفعيل الفوترة يعني أنني سأُحاسَب فوراً؟

تدفع مقابل الاستخدام الذي يتجاوز المسموح المجاني، لا مقابل ربط الحساب. اضبط تنبيهات ميزانية في اليوم نفسه الذي تفعّله فيه حتى تُرسل ذروة مفاجئة بريداً بدل صدمة فاتورة.

سجل التغييرات

  • — نُشر. تم التحقق من شرط المنطقة، وحل الفوترة، وقالب الخطأ، من دليل Google لاستكشاف أخطاء Gemini API.

المصادر

  • توثيق استكشاف أخطاء Gemini API: ai.google.dev/gemini-api/docs/troubleshooting (تم التحقق في 12 يونيو 2026)
  • benchr api-errors.json (المُدخل المنظَّم لهذا الخطأ)