این صفحه عیب‌یابی کدهای خطای رایج برای کیت‌های توسعه نرم‌افزار Gemini API و Firebase AI Logic را ارائه می‌دهد.
خطای ۴۰۰: API key not valid. Please pass a valid API key.
اگر خطای ۴۰۰ دریافت کردید که می‌گوید
API key not valid. Please pass a valid API key.، معمولاً به این معنی است که
کلید API در فایل/شیء پیکربندی Firebase شما وجود ندارد یا برای استفاده با برنامه و/یا پروژه Firebase شما تنظیم نشده است.
بررسی کنید که کلید API فهرست‌شده در فایل/شیء پیکربندی Firebase شما با کلید API برنامه شما مطابقت داشته باشد. می‌توانید همه کلیدهای API خود را در پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری در کنسول Google Cloud مشاهده کنید.
اگر متوجه شدید که مطابقت ندارند، یک فایل/ شیء پیکربندی Firebase جدید دریافت کنید، و سپس فایل/ شیء موجود در برنامه‌تان را جایگزین کنید. فایل/ شیء پیکربندی جدید باید حاوی کلید API معتبری برای برنامه و پروژه Firebase شما باشد.
خطای ۴۰۰: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
اگر می‌خواهید درخواست چندوجهی با Cloud Storage for Firebase
نشانی وب ارسال کنید، ممکن است با خطای ۴۰۰ زیر مواجه شوید:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
این خطا به‌دلیل پروژه‌ای است که وقتی Agent Platform API در پروژه فعال شد، عامل‌های سرویس موردنیاز به‌درستی به‌طور خودکار آماده نشده بودند. این مشکلی شناخته‌شده در برخی پروژه‌ها است و درحال کار روی رفع جهانی آن هستیم.
در اینجا راهکاری برای اصلاح پروژه و آماده‌سازی صحیح این کارگزاران خدمات ارائه شده است تا بتوانید Cloud Storage for Firebase نشانی وب را در درخواست‌های چندوجهی خود بگنجانید. باید در پروژه مالک باشید و فقط یک‌بار باید این مجموعه کارها را برای پروژه‌تان تکمیل کنید.
با gcloud CLI دسترسی پیدا کنید و اصالت‌سنجی کنید.
آسان‌ترین راه برای انجام این کار از Cloud Shell است. در Google Cloud سند اطلاعات بیشتری کسب کنید.اگر پیام‌واره‌ای دریافت کردید، دستورالعمل‌های نمایش‌داده‌شده در پایانه را دنبال کنید تا gcloud CLI را دربرابر پروژه Firebase خود اجرا کنید.
به شناسه پروژه Firebase خود نیاز دارید که می‌توانید آن را در بالای settings تنظیمات پروژه در کنسول Firebase پیدا کنید.
با اجرای فرمان زیر، کارگزاران خدمات موردنیاز را در پروژه‌تان آماده کنید:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
چند دقیقه صبر کنید تا مطمئن شوید کارگزاران سرویس آماده شده‌اند، و سپس درخواست چندوجهی خود را که شامل نشانی وب Cloud Storage for Firebase است دوباره ارسال کنید.
اگر پس‌از چند دقیقه همچنان این خطا را دریافت می‌کنید، با پشتیبانی Firebase تماس بگیرید.
خطای ۴۰۳: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
اگر خطای 403 - PERMISSION_DENIED دریافت کردید که می‌گوید
To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check،
یعنی درخواست شما دارای کد App Check معتبر نیست و
می‌خواهید به مدلی دسترسی پیدا کنید که معمولاً مورد سوءاستفاده قرار می‌گیرد.
برخی‌از مدل‌های زایا به‌عنوان مدل‌های رایج برای سوءاستفاده عاملان بدخواه شناسایی شده‌اند.
چون App Check را برای Firebase AI Logic اعمال نکرده‌اید، پروژه شما دربرابر سوءاستفاده از این مدل‌ها آسیب‌پذیر است. برای کمک به محافظت از توسعه‌دهندگانمان، Firebase دسترسی به این مدل‌ها را مسدود می‌کند، مگر اینکه درخواست شامل App Check معتبر باشد (یعنی App Check برای Firebase AI Logic اعمال می‌شود).
اگر می‌خواهید به مدلی که خطا را برگردانده است دسترسی پیدا کنید، این کارها را انجام دهید:
App Check را برای Firebase AI Logic راه‌اندازی کنید. برای توسعه محلی، مطمئن شوید که App Check ارائه‌دهنده اشکال‌زدایی را راه‌اندازی کرده‌اید.
اجرای App Check برای کمک به محافظت از مدل‌های Gemini API و Gemini دربرابر سوءاستفاده بسیار مهم است و اجرای آن برای رفع این خطا الزامی است.
درخواست را از برنامه‌تان به Firebase AI Logic مجدداً ارسال کنید.
این درخواست یک کد App Check معتبر را ارسال می‌کند و دیگر خطای
403 - PERMISSION_DENIEDرا دریافت نخواهید کرد.قبل‌از اینکه برنامه‌تان را برای کاربران نهایی منتشر کنید، باید ارائه‌دهنده گواهی تولید راه‌اندازی کنید (مثل App Attest، «تمامیت Play»، یا reCAPTCHA Enterprise) تا کاربران نهایی شما بتوانند وقتی App Check اعمال می‌شود به ویژگی هوش مصنوعی شما دسترسی داشته باشند.
خطای ۴۰۳: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
اگر خطای 403 - PERMISSION_DENIED دریافت کردید که می‌گوید
Firebase AI Logic has been deactivated in this project. To resume using
Firebase AI Logic, you must enforce Firebase App Check. Learn more:
https://firebase.google.com/docs/ai-logic/app-check،
یعنی پروژه Firebase شما به‌عنوان غیرفعال شناسایی شده است و
App Check برای Firebase AI Logic برای شما اعمال نشده است.
«پروژه‌های غیرفعال» پروژه‌هایی هستند که Firebase AI Logic در آن‌ها فعال است، اما اخیراً از Firebase AI Logic استفاده‌ای نداشته‌اند.
چون App Check را برای Firebase AI Logic اعمال نکرده‌اید، پروژه شما دربرابر سوءاستفاده از Gemini API آسیب‌پذیر است. برای کمک به محافظت از پروژه شما، Firebase استفاده از Firebase AI Logic را تا زمانی‌که App Check را برای Firebase AI Logic اعمال کنید غیرفعال کرد.
وقتی آماده شدید دوباره از Firebase AI Logic استفاده کنید، کارهای زیر را انجام دهید:
App Check را برای Firebase AI Logic راه‌اندازی کنید. برای توسعه محلی، مطمئن شوید که App Check ارائه‌دهنده اشکال‌زدایی را راه‌اندازی کرده‌اید.
اجرای App Check برای کمک به محافظت از مدل‌های Gemini API و Gemini دربرابر سوءاستفاده بسیار مهم است و اجرای آن برای رفع این خطا الزامی است.
درخواست را از برنامه‌تان به Firebase AI Logic مجدداً ارسال کنید.
این درخواست یک کد App Check معتبر را ارسال می‌کند و دیگر خطای
403 - PERMISSION_DENIEDرا دریافت نخواهید کرد.اگر ازقبل App Check را اعمال می‌کنید و همچنان این خطا را دریافت می‌کنید، بررسی کنید که آیا محافظت دربرابر بازپخش برای Firebase AI Logic (ازجمله در حالت «فقط نظارت») روشن است یا خیر.
وقتی محافظت دربرابر بازپخش روشن باشد، فقط کدهای با استفاده محدود به‌عنوان درستی‌سنجی‌شده برای Firebase AI Logic محسوب می‌شوند؛ کدهای جلسه معمولی این خطا را برطرف نمی‌کنند. یا در برنامه‌تان، نشان‌های محدوداستفاده را فعال کنید، یا محافظت دربرابر بازپخش را برای Firebase AI Logic خاموش کنید، درخواستی را دوباره ارسال کنید، و حدود یک روز صبر کنید و سپس محافظت دربرابر بازپخش را دوباره روشن کنید (فعالیت پروژه هر روز دوباره ارزیابی می‌شود).
قبل‌از اینکه برنامه‌تان را برای کاربران نهایی منتشر کنید، باید ارائه‌دهنده گواهی تولید راه‌اندازی کنید (مثل App Attest، «تمامیت Play»، یا reCAPTCHA Enterprise) تا کاربران نهایی شما بتوانند وقتی App Check اعمال می‌شود به ویژگی هوش مصنوعی شما دسترسی داشته باشند.
خطای ۴۰۳: PERMISSION_DENIED: The caller does not have permission.
اگر خطای ۴۰۳ دریافت کردید که می‌گوید
PERMISSION_DENIED: The caller does not have permission.، معمولاً به این معنی است که
کلید API در فایل/شیء پیکربندی Firebase شما متعلق به
پروژه Firebase دیگری است.
بررسی کنید که کلید API فهرست‌شده در فایل/شیء پیکربندی Firebase شما با کلید API برنامه شما مطابقت داشته باشد. می‌توانید همه کلیدهای API خود را در پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری در کنسول Google Cloud مشاهده کنید.
اگر متوجه شدید که مطابقت ندارند، یک فایل/ شیء پیکربندی Firebase جدید دریافت کنید، و سپس فایل/ شیء موجود در برنامه‌تان را جایگزین کنید. فایل/ شیء پیکربندی جدید باید حاوی کلید API معتبری برای برنامه و پروژه Firebase شما باشد.
خطای ۴۰۳: Requests to this API firebasevertexai.googleapis.com ... are blocked.
اگر خطای ۴۰۳ دریافت کردید که می‌گوید
Requests to this API firebasevertexai.googleapis.com ... are blocked.، معمولاً به این معنی است که کلید API در پیکربندی Firebase در برنامه شما محدودیت‌هایی دارد که مانع از فراخوانی API موردنیاز می‌شود.
برای رفع این مشکل، باید محدودیت‌های کلید API خود را در کنسول Google Cloud به‌روز کنید تا میانای برنامه‌سازی کاربردی موردنیاز را دربر بگیرد. برای Firebase AI Logic،
باید مطمئن شوید که Firebase AI Logic API
(firebasevertexai.googleapis.com) در فهرست
میاناهای برنامه‌سازی کاربردی انتخابی که می‌توانند بااستفاده از کلید API فراخوانی شوند اضافه شده باشد.
این مراحل را دنبال کنید:
در کنسول Google Cloud، پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری را باز کنید.
کلید API را که برنامه‌تان برای استفاده از آن پیکربندی شده است انتخاب کنید (برای مثال، «کلید iOS» برای برنامه iOS).
در صفحه ویرایش کلید API، بخش محدودیت‌های API را پیدا کنید.
مطمئن شوید که گزینه کلید محدود کردن انتخاب شده باشد. اگر این‌طور نیست، کلید شما بدون محدودیت است و احتمالاً منبع خطا نیست.
در منوِ کرکره‌ای میاناهای برنامه‌سازی کاربردی انتخاب‌شده، Firebase AI Logic میانای برنامه‌سازی کاربردی را جستجو و انتخاب کنید تا به فهرست میاناهای برنامه‌سازی کاربردی انتخاب‌شده اضافه شود و بتواند بااستفاده از کلید میانای برنامه‌سازی کاربردی فراخوانی شود.
روی ذخیره کردن کلیک کنید.
ممکن است اعمال تغییرات تا پنج دقیقه طول بکشد.
خطای ۴۰۴: Firebase AI Logic genai config not found
اگر خطای ۴۰۴ دریافت کردید که می‌گوید Firebase AI Logic genai config not found،
معمولاً به این معنی است که تنظیم Firebase AI Logic پیکربندی اشتباهی دارد یا
وجود ندارد.
در اینجا محتمل‌ترین دلایل این خطا آورده شده است:
هنوز پروژه Firebase خود را برای ارائه‌دهنده Gemini API راه‌اندازی نکرده‌اید.
اقدامات لازم:
در کنسول Firebase، به خدمات هوش مصنوعی > منطق هوش مصنوعی بروید. روی شروع به کار کلیک کنید، و سپس ارائه‌دهنده Gemini API انتخابی‌تان را انتخاب کنید. «میانای برنامه‌سازی کاربردی» را فعال کنید و Firebase پروژه شما را برای آن ارائه‌دهنده راه‌اندازی خواهد کرد. پس‌از تکمیل گردش کار، درخواستتان را دوباره امتحان کنید.اگر به‌تازگی گردش کار راه‌اندازی Firebase AI Logic را در کنسول Firebase انجام داده‌اید، ممکن است پیکربندی Firebase AI Logic هنوز برای همه خدمات زیرینه موردنیاز در همه مناطق ذی‌ربط دردسترس نباشد.
چه باید کرد:
چند دقیقه صبر کنید، و سپس درخواستتان را دوباره امتحان کنید.
خطای ۴۰۴: مدل «was not found or your project does not have access to it»؟
برای مثال: «Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version.»
چند دلیل مختلف وجود دارد که ممکن است با چنین خطایی مواجه شوید.
نام مدل نامعتبر است
علت: نام مدلی که ارائه کرده‌اید نام مدل معتبری نیست.
رفع مشکل: نام مدل و نسخه مدل خود را با فهرست همه مدل‌های پشتیبانی‌شده و دردسترس بررسی کنید. حتماً بخش‌ها و ترتیب آن‌ها را در نام مدل بررسی کنید. برای مثال:
- نام جدیدترین مدل Gemini 3.x Pro:
gemini-3.1-pro-preview(فقط در پیش‌نمایش دردسترس است) - آخرین Gemini 3.x Flash
نام مدل:
gemini-3.8-flash - آخرین Gemini 3.x Flash‑Lite
نام مدل:
gemini-3.5-flash-lite - جدیدترین Gemini 3.x Pro Image (با نام مستعار «Nano Banana Pro»)
نام مدل:
gemini-3-pro-image - جدیدترین Gemini 3.x Flash Image (با نام مستعار «Nano Banana 2»)
نام مدل:
gemini-3.1-flash-image - جدیدترین Gemini 3.x Flash‑Lite Image (با نام مستعار «Nano Banana 2 Lite»)
نام مدل:
gemini-3.1-flash-lite-image - جدیدترین Gemini 2.5 Flash Image (معروف به «نانو موز»)
نام مدل:
gemini-2.5-flash-image
- نام جدیدترین مدل Gemini 3.x Pro:
مکان نامعتبر است (فقط درصورت استفاده از ارائه‌دهنده Agent Platform Gemini API (formerly Vertex AI) اعمال می‌شود)
دلیل: درخواست شما ممکن است سعی در دسترسی به مدلی در مکانی داشته باشد که مدل در آنجا دردسترس نیست.
رفع مشکل: مطمئن شوید که درخواست شما سعی در دسترسی به مدلی دارد که در آن دسترسی به آن امکان‌پذیر است.
هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI)، می‌توانید به‌صورت اختیاری مکان دسترسی به مدل را درطول مقداردهی اولیه مشخص کنید. اگر مکان را مشخص نکنید، Firebase AI Logic به‌طور پیش‌فرض از مکان‌های زیر استفاده می‌کند:
- هنگام استفاده از نحو مقداردهی اولیه «پلاتفرم نماینده»:
global - هنگام استفاده از دستورگان قدیمی مقداردهی اولیه «Vertex AI»:
us-central1
بااین‌حال، همه مدل‌ها در این مکان‌های پیش‌فرض پشتیبانی نمی‌شوند. این یعنی بسته به مدل، ممکن است لازم باشد مکان خاصی را درطول مقداردهی اولیه صریحاً تنظیم کنید.
Gemini پیش‌نمایش و مدل‌های آزمایشی: فقط در مکان
globalدردسترس است.Gemini 3.x مدل پایدار: در
globalمکان و اغلب درusوeuمکان دردسترس است.Gemini 2.5 مدل: در بسیاری از مکان‌ها دردسترس است. توجه داشته باشید که مدل‌های Gemini Live API 2.5 در
globalدردسترس نیستند.
- هنگام استفاده از نحو مقداردهی اولیه «پلاتفرم نماینده»:
درباره نحوه مشخص کردن مکان برای دسترسی به مدل (ازجمله تکه‌کدهای) بیشتر بدانید.
خطاهای ۴۲۹: "You exceeded your current quota, please check your plan and billing details" یا "Resource exhausted, please try again later."
چند دلیل مختلف وجود دارد که ممکن است با چنین خطایی مواجه شوید.
از سهمیه خود فراتر رفته‌اید یا مدلی که به آن دسترسی دارید به‌دلیل درخواست‌های دیگران بیش‌ازحد بارگذاری شده است.
اقدام موردنیاز به اینکه از Gemini Developer API یا Agent Platform Gemini API (formerly Vertex AI) استفاده می‌کنید بستگی دارد. برای اطلاعات بیشتر درباره سهمیه‌ها و نحوه درخواست سهمیه اضافی، حدود نرخ و سهمیه‌ها را ببینید.
اگر از Agent Platform Gemini API (formerly Vertex AI) استفاده می‌کنید، Google Cloud مستندات زمینه و راهنمایی‌های بیشتری برای کد خطای ۴۲۹ ارائه می‌دهد.
سعی می‌کنید از مدل یا ویژگی‌ای استفاده کنید که به صورت‌حساب نیاز دارد، اما پروژه Firebase شما در طرح قیمت‌گذاری Spark است.
اگر از Gemini Developer API استفاده می‌کنید، می‌توانید درحالی‌که در «سطح رایگان» Gemini Developer API هستید، به برخی‌از مدل‌ها دسترسی محدود و به بسیاری از ویژگی‌های پایه دسترسی داشته باشید. این سطح به شما امکان می‌دهد بدون نیاز به ارائه روش پرداخت شروع کنید، یعنی لازم نیست پروژه Firebase خود را به طرح قیمت‌گذاری «شعله» با پرداخت براساس مصرف ارتقا دهید.
برخی‌از مدل‌ها در Gemini Developer API «سطح رایگان» دردسترس نیستند و به «سطح پولی» نیاز دارند، که یعنی پروژه شما باید در طرح قیمت‌گذاری Blaze با پرداخت براساس مصرف باشد. برای مثال، مدل‌های زیر تقریباً همیشه به صورت‌حساب نیاز دارند:
- بیشتر مدل‌های پیش‌نمایش و آزمایشی
- مدل‌های تولید تصویر (مدل‌های «Nano Banana»)
برخی‌از مدل‌ها در Gemini Developer API «سطح رایگان» برخی‌از ویژگی‌های پایه را ارائه می‌دهند، اما برای استفاده از ویژگی‌های پیشرفته‌تر به «سطح پولی» نیاز دارند. برای مثال:
- هنگام استفاده از اکثر مدل‌های Gemini 3.x،
«پایه‌گذاری» با
Google Search یاGoogle Maps نیاز به صورت‌حساب دارد.
- هنگام استفاده از اکثر مدل‌های Gemini 3.x،
«پایه‌گذاری» با
درباره طرح‌های قیمت‌گذاری Firebase و Gemini Developer API بیشتر بدانید.
برای جزئیات بیشتر، Gemini Developer API مستندات قیمت‌گذاری و پرسشگان صورت‌حساب را ببینید.