أخطاء Gemini API: 401 و404 و429 وقيود المنطقة (2026)

تبدو أخطاء Gemini API متعددة الأسماء، لكنها عمليًا تعود غالبًا إلى أربعة أنواع: هوية خاطئة، وعنوان خاطئ، وحصة غير كافية، وشبكة لا تصل. المشكلات الناتجة عن الطراز نفسه أقل شيوعًا.

تقسم هذه المقالة الأخطاء حسب الرمز، وتقدم ترتيب فحص يبدأ من أصغر طلب. عند حدوث مشكلة، احفظ أولًا ملف JSON الكامل للخطأ، ثم تحقق بالترتيب، ولا تغيّر المفتاح والعنوان والطراز في الوقت نفسه.

ملاحظة: Google وGemini علامتان تجاريتان تخصان مالكيهما. تعتمد المقالة على شكل الواجهة الشائع في أكتوبر 2026؛ إصدار الواجهة والحصص وسياسة المناطق تتبع الوثائق الرسمية وأسعار الطرازات.

أولًا: اقرأ جسم الخطأ أولًا

تعيد واجهات Google عادةً خطأً بصيغة JSON، وفيه ثلاثة حقول أساسية:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code هو رمز حالة HTTP، وstatus نوع الخطأ المقروء آليًا، ويحتوي message غالبًا على السبب المحدد، وقد تحتوي details على معرّف الحصة ووقت إعادة المحاولة المقترح. اقرأ الثلاثة معًا؛ رؤية «429» وحدها تخفي ما إذا كانت المشكلة تحديدًا دقيقيًا أم نفاد الحصة اليومية.

رمز الحالة	status الشائع	الاتجاه العام
401	UNAUTHENTICATED	مفتاح مفقود أو غير صالح أو في موضع خاطئ
403	PERMISSION_DENIED	المشروع غير مفعّل أو الصلاحية أو المنطقة مقيدة
404	NOT_FOUND	اسم الطراز أو مسار الواجهة أو الإصدار خاطئ
429	RESOURCE_EXHAUSTED	تجاوز السرعة أو التزامن أو الحصة
400	INVALID_ARGUMENT / FAILED_PRECONDITION	معامل خاطئ أو منطقة غير مدعومة أو شرط مسبق غير متحقق
500/503	INTERNAL / UNAVAILABLE	عطل مؤقت لدى المزود، ويصلح معه التراجع وإعادة المحاولة

ثانيًا: 401: مفتاح غير صالح أو طريقة مصادقة خاطئة

جوهر 401 أن «الخادم لا يعرف هويتك». الأسباب الشائعة:

• الطلب لا يحمل مفتاحًا أصلًا، أو متغير البيئة فارغ.
• الواجهة الأصلية تستخدم Authorization بدل x-goog-api-key.
• الواجهة المتوافقة مع OpenAI تستخدم x-goog-api-key بدل Authorization: Bearer.
• مسافات أو أسطر جديدة أو علامات اقتباس حول المفتاح عند النسخ.
• حُذف المفتاح أو أُعيد تدويره أو أُوقف المشروع التابع له.
• أُرسل مفتاح البوابة إلى عنوان Google، أو العكس.
• للمفتاح قيود API تمنع استدعاء Gemini API.

تحقق أولًا بطلب أدنى:

export GEMINI_API_KEY="مفتاحك"

# واجهة Gemini الأصلية
curl "https://generativelanguage.googleapis.com/v1beta/models/<معرّف الطراز>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"أعد OK فقط"}]}]}'

# الواجهة المتوافقة مع OpenAI
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<معرّف الطراز>","messages":[{"role":"user","content":"أعد OK فقط"}]}'

الأمران يقابلان نظامي مصادقة. أي أمر ينجح يحدد النظام الذي ينتمي إليه مفتاحك وعنوانك؛ ظهور 401 عند الخلط لا يعني أن المفتاح تلف، بل أن التركيبة خاطئة.

ثالثًا: 404: اسم الطراز أو المسار أو الإصدار خاطئ

404 لا يعني بالضرورة أن «الطراز غير موجود». الحالات الشائعة:

1. معرّف الطراز مكتوب خطأ، أو استُخدم الاسم المعروض في لوحة التحكم بدل معرّف API.
2. الطراز لا ينتمي إلى إصدار API الحالي، مثل إرسال طراز متاح في إصدار جديد إلى مسار قديم.
3. Base URL يزيد أو ينقص /v1 أو /v1beta، فيصبح المسار بعد التجميع غير موجود.
4. شرطة مائلة زائدة في نهاية العنوان، فيضيف العميل المسار مرة أخرى.
5. عند الاستدعاء عبر بوابة، الطراز غير مفعّل في المجموعة أو الباقة الحالية.
6. استُخدمت واجهة المحادثة لاستدعاء توليد الصور أو واجهة متخصصة أخرى.

ابدأ بسرد الطرازات المتاحة للمفتاح الحالي:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

إذا ظهر الطراز الهدف في القائمة، فتحقق من مسار الطلب؛ وإذا لم يظهر، فعالج تفعيل الطراز أو الصلاحية أولًا. عند الاستدعاء عبر بوابة، اعتمد معرّف الطراز وBase URL اللذين توثقهما البوابة، ولا تُسقط اسم الطراز الرسمي مباشرة.

رابعًا: 429: ميّز تحديد المعدل من نفاد الحصة

429 من أكثر الأخطاء عرضةً لسوء التفسير، ويشمل ثلاث حالات على الأقل:

النوع	السمة النموذجية	اتجاه المعالجة
تحديد دقيقي	تزامن مرتفع لفترة قصيرة وأخطاء خلال ثوانٍ	خفّض التزامن وأعد المحاولة بتراجع
نفاد الحصة اليومية	بلوغ سقف اليوم وفشل مستمر	انتظر التجديد أو ارفع الحصة أو غيّر الخطة
حصة على مستوى المشروع	عدة خدمات تشترك في مشروع وتتنافس	افصل المشاريع والمفاتيح والحصص

تعطي details في جسم الخطأ عادةً معرّف الحصة ووقت إعادة المحاولة المقترح. لا تُعد الإرسال فور رؤية 429؛ عاصفة الإعادة تزيد الوضع سوءًا. ثبّت الاعتماد أولًا: pip install requests. ومنطق تراجع عملي:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<معرّف الطراز>:generateContent"
    headers = {
        "x-goog-api-key": "مفتاحك",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("استُهلكت محاولات إعادة الإرسال")

إعادة المحاولة تحل الازدحام المؤقت فقط، لا نفاد الحصة. تحتاج بيئة الإنتاج أيضًا إلى مهلة وقاطع دائرة وطراز بديل، وإلا أسقط 429 واحد السلسلة كلها.

خامسًا: قيود المنطقة: لماذا يفشل الاتصال المباشر داخل الصين

تقدم Gemini API خدماتها في بعض الدول والمناطق فقط. عندما يقع منفذ الطلب في منطقة غير مدعومة، تظهر ثلاث حالات شائعة:

• مهلة اتصال أو فشل مصافحة TLS، وغالبًا بسبب مسار شبكي غير قابل للوصول.
• استجابة 400 FAILED_PRECONDITION تتضمن عبارة مثل location is not supported.
• استجابة 403 PERMISSION_DENIED قد ترتبط بالمشروع أو الفوترة أو صلاحية المنطقة.

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

الترتيب المقترح للمعالجة:

1. حدد ما إذا كان الطلب يخرج من الجهاز أو الحاوية أو الخادم، واعرف عنوان IP الحقيقي للمنفذ.
2. تحقق مما إذا كانت منطقة المنفذ ضمن قائمة الدعم الرسمية.
3. افحص منطقة الخادم السحابي، وبدّلها إلى منطقة مدعومة عند الحاجة.
4. إذا كان العمل داخل الصين أساسًا، فقيّم الوصول عبر بوابة متوافقة تعالج الشبكة والفاتورة معًا.
5. لا تجعل «تغيير IP» الحل الوحيد، بل تحقق أولًا من شروط الخدمة واللوائح المحلية.

سادسًا: أخطاء متكررة أخرى

الظاهرة	السبب الشائع	المعالجة
400 INVALID_ARGUMENT	بنية JSON خاطئة أو ترتيب أدوار غير صحيح أو صيغة صورة غير مدعومة	ابدأ بطلب أدنى وأضف الحقول تدريجيًا
400 FAILED_PRECONDITION	منطقة غير مدعومة أو فوترة غير مفعّلة أو شرط مسبق ناقص	افحص المنطقة والفوترة وحالة المشروع
403 PERMISSION_DENIED	API غير مفعّل أو قيود المفتاح أو صلاحية المشروع	فعّل من لوحة التحكم وتحقق من الصلاحيات
500 INTERNAL	خطأ داخلي لدى المزود	تراجع وأعد المحاولة وسجّل معرّف الطلب
503 UNAVAILABLE	حمل زائد أو صيانة لدى المزود	تراجع وأعد المحاولة وبدّل الطراز البديل
استجابة بلا محتوى	اعتراض سياسة الأمان أو اقتطاع الإخراج	افحص blockReason وfinishReason
توقف الإخراج في المنتصف	بلوغ حد Tokens الإخراج	ارفع الحد أو اختصر الإدخال

كثيرًا ما تُعد «الاستجابة بلا محتوى» عطلًا، وهي في الحقيقة تصفية أمان أو حد طول. افحص promptFeedback.blockReason وfinishReason وusageMetadata في الاستجابة، ثم قرر تعديل المطالبة أو المعاملات.

سابعًا: ترتيب الفحص الموصى به

1. احفظ ملف JSON الكامل للخطأ ووقت الطلب ومعرّف الطراز ومعرّف الطلب.
2. أرسل طلبًا أدنى بـcurl لعزل تأثير العميل وSDK.
3. تحقق من ثلاثة أمور: Base URL ورأس المصادقة ومعرّف الطراز.
4. بدّل إلى طراز معروف بالعمل، لتحديد ما إذا كانت المشكلة في الطراز أم المسار.
5. راجع الحصة والفوترة وحالة المشروع، وميّز 429 من 403.
6. تأكد من منطقة منفذ الطلب والمسار الشبكي.
7. افحص أخيرًا إعدادات العميل والوكيل ومنطق إعادة المحاولة في الشيفرة.

غيّر متغيرًا واحدًا في كل مرة. وإلا فلن تعرف أي خطوة أصلحت المشكلة حتى بعد التعافي، وستكرر الخطأ لاحقًا.

ثامنًا: الأسئلة الشائعة

ما الفرق بين 401 و403؟

401 تعني «الهوية لم تُقبل»، فتحقق من المفتاح ورأس المصادقة وتطابق العنوان؛ و403 تعني «الهوية قُبلت لكن لا صلاحية»، فتحقق من تفعيل API وصلاحيات المشروع وقيود المفتاح وسياسة المنطقة.

هل يكفي الانتظار دقائق بعد 429؟

يعتمد على نوع الحصة. تحديد الدقيقة يتعافى عادةً بعد التراجع؛ ونفاد الحصة اليومية يحتاج انتظار التجديد أو رفع الحصة. اقرأ معرّف الحصة ونصيحة الإعادة في جسم الخطأ، ولا تُعد الإرسال عشوائيًا.

هل تغيير IP يحل قيود المنطقة؟

ليس بالضرورة. الأمر يعتمد على منطقة المنفذ الحقيقية وحالة الحساب وشروط الخدمة. في سياق المؤسسة، الأكثر أمانًا النشر في منطقة مدعومة أو الوصول عبر بوابة متوافقة.

العنوان الرسمي يعمل، وعبر البوابة يعيد 404. من المسؤول؟

تحقق أولًا من Base URL ومعرّف الطراز لدى البوابة. قد تختلف تسمية الطرازات والمسارات والنطاق عن الاسم الرسمي، ولا يصح نسخ الطلب الرسمي مباشرة. استبدل البنود واحدًا واحدًا وفق أصغر مثال في وثائق البوابة.

كيف أمنع إعادة المحاولة من مضاعفة التكلفة؟

اضبط حدًا أقصى للمحاولات وتراجعًا أسيًا ومهلة؛ وعالج 429 منفصلًا؛ وأضف إزالة تكرار للطلبات غير المتكررة؛ واضبط سقف ميزانية وتنبيهًا على جانب البوابة.

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

مفتاح تشخيص أخطاء Gemini هو التمييز أولًا بين «المصادقة والمسار والحصة والشبكة»، ثم التحقق بطلب أدنى بندًا بندًا. إذا احتجت مدخلًا موحدًا يقلل عدم يقين الاتصال المباشر داخل الصين، يمكنك التسجيل في ZSQH AI Gateway؛ الطرازات والحصص والأسعار تتبع صفحة أسعار الطرازات.

قراءات ذات صلة:

• إعداد Gemini API: المفتاح والاستدعاء
• Gemini API في الصين: الوصول والاستقرار
• بدائل Gemini API للمؤسسات