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

‏403 ليس فشل مصادقة

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

السؤال العملي ليس «هل المفتاح يعمل؟» بل «أي مشروع يملك المفتاح، وما الذي يستطيع هذا المشروع استدعاءه، وأي قيد يسري في هذه البيئة؟». التطوير المحلي والإنتاج يستخدمان كثيراً مشروعين ومفتاحين وقيوداً مختلفة. لذلك قد ينجح الطلب في جهازك ويفشل في worker أو API منشور.

افحص الطلب بهذا الترتيب

تتبع خطأ Gemini 403 من سر الإنتاج حتى المورد المطلوب.

الفحص	ما الذي تبحث عنه	لماذا يهم
المشروع المالك	المشروع الذي أنشأ مفتاح API في الإنتاج	قد لا ينتمي سر الإنتاج إلى المشروع الذي أعددته محلياً.
قيود المفتاح	APIs والبيئات أو العناوين أو الأصول المسموح بها	قد يرفض قيد مفتاح صحيحاً بعد النشر.
المورد المطلوب	النموذج أو الميزة وتوفرها لهذا المشروع	المفتاح الصحيح لا يمنح كل القدرات تلقائياً.

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

شكل الاستجابة

توثق Google رموز الأخطاء بشكل موحد. قد يتغير نص الرسالة، لذلك اجعل كودك يتفرع على الحالة الثابتة لا على جملة من السجل.

{
  "error": {
    "code": 403,
    "message": "Permission denied.",
    "status": "PERMISSION_DENIED"
  }
}

خطأ 403 إشارة توقف لإعادة المحاولة التلقائية. تفيد backoff في 429 أو 503 العابرين، لكنها لا تمنح صلاحيات. اعتبر تكرار 403 تنبيهاً لإعداد النشر. إذا تحوّل الخطأ بعد إصلاح الوصول إلى NOT_FOUND، افحص معرف المورد أو النموذج حرفياً. وإذا أصبح FAILED_PRECONDITION، فقد تبقى فوترة أو متطلبات أخرى للحساب.

حل آمن في الكود والنشر

# اجعل الإعداد صريحاً؛ لا تطبع المفتاح أبداً.
MODEL = "gemini-3.6-flash"
PROJECT_LABEL = "production-gemini"  # بيانات نشر، ليست اعتماداً

# قبل تمرير الحركة، أرسل طلب smoke صغيراً من سر ومسار الإنتاج.
# نبه على HTTP 403 ولا تعد المحاولة تلقائياً.

لا تعالج الخطأ بإزالة كل القيود أو مشاركة مفتاح واسع بين البيئات. استخدم مفتاحاً مسمى منفصلاً للمحلي وstaging والإنتاج، وامنح الوصول المقصود فقط، وضع اختبار smoke في النشر. بذلك يظهر الخطأ قبل العملاء، ويصبح أي 403 لاحق سهل التتبع.

أسئلة شائعة

هل أعيد محاولة Gemini permission_denied؟

لا. المشكلة الموثقة هي غياب صلاحية وليست سعة مؤقتة. أعد المحاولة بعد تغيير الوصول أو قيد المفتاح المقصود.

هل يعني 403 أن مفتاح API غير صالح؟

لا. تستخدم Gemini خطأ مصادقة منفصلاً للمفتاح المفقود أو غير الصالح أو المنتهي. 403 يعني أن المفتاح المتعرّف عليه لا يملك صلاحية المورد.

لماذا يعمل محلياً ويفشل في الإنتاج؟

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

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

• 14 أغسطس 2026 — نُشر بعد التحقق من جدول أخطاء Gemini API الحالي لدى Google، المحدث في 5 أغسطس 2026.

المصادر

• Google، أخطاء Gemini API — يعرّف permission_denied كـ HTTP 403 ويوجه المطور إلى فحص صلاحيات المفتاح ووصول المشروع؛ تم التحقق في 14 أغسطس 2026.