این صفحه عیب‌یابی کدهای خطای رایج برای کیت‌های توسعه نرم‌افزار 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 شما استفاده شود.
بررسی کنید که کلید میانای برنامه‌سازی کاربردی فهرست‌شده در فایل/شیء پیکربندی Firebase با کلید میانای برنامه‌سازی کاربردی برنامه‌تان مطابقت داشته باشد. می‌توانید همه کلیدهای میانای برنامه‌سازی کاربردی خود را در پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات کاربری در کنسول Google Cloud مشاهده کنید.
اگر متوجه شدید که مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید، و سپس آن را در برنامه خود جایگزین کنید. فایل/شیء پیکربندی جدید باید حاوی یک کلید میانای برنامه‌سازی کاربردی معتبر برای برنامه و پروژه 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 در پروژه، عامل‌های سرویس موردنیاز به‌درستی به‌طور خودکار برای آن فراهم نشده است. این مشکل شناخته‌شده‌ای در برخی پروژه‌ها است و درحال کار روی راه‌حلی کلی هستیم.
در اینجا راه‌حل موقتی برای رفع مشکل پروژه شما و تأمین صحیح این عامل‌های سرویس ارائه شده است تا بتوانید افزودن نشانی‌های وب 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 Integrity، یا 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 Integrity، یا reCAPTCHA Enterprise) تا کاربران نهایی شما بتوانند هنگام اجرای App Check به ویژگی هوش مصنوعی شما دسترسی داشته باشند.
خطای ۴۰۳: PERMISSION_DENIED: The caller does not have permission.
اگر خطای ۴۰۳ دریافت کردید که می‌گوید
PERMISSION_DENIED: The caller does not have permission.، معمولاً به این معنی است که
کلید میانای برنامه‌سازی کاربردی در فایل/ شیء پیکربندی Firebase شما متعلق به
پروژه Firebase دیگری است.
بررسی کنید که کلید میانای برنامه‌سازی کاربردی فهرست‌شده در فایل/شیء پیکربندی Firebase با کلید میانای برنامه‌سازی کاربردی برنامه‌تان مطابقت داشته باشد. می‌توانید همه کلیدهای میانای برنامه‌سازی کاربردی خود را در پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات کاربری در کنسول Google Cloud مشاهده کنید.
اگر متوجه شدید که مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید، و سپس آن را در برنامه خود جایگزین کنید. فایل/شیء پیکربندی جدید باید حاوی یک کلید میانای برنامه‌سازی کاربردی معتبر برای برنامه و پروژه Firebase شما باشد.
خطای ۴۰۳: Requests to this API firebasevertexai.googleapis.com ... are blocked.
اگر خطای ۴۰۳ دریافت کردید که می‌گوید
Requests to this API firebasevertexai.googleapis.com ... are blocked.، معمولاً به این معنی است که کلید میانای برنامه‌سازی کاربردی در پیکربندی Firebase در برنامه‌تان محدودیت‌هایی دارد که مانع از فراخوانی میانای برنامه‌سازی کاربردی موردنیاز می‌شود.
برای رفع این مشکل، باید محدودیت‌های کلید میانای برنامه‌سازی کاربردی خود را در کنسول Google Cloud به‌روز کنید تا میانای برنامه‌سازی کاربردی موردنیاز را دربرگیرد. برای Firebase AI Logic،
باید مطمئن شوید Firebase AI Logic API
(firebasevertexai.googleapis.com) در فهرست میاناهای برنامه‌سازی کاربردی انتخاب‌شده
که می‌توانند بااستفاده از کلید میانای برنامه‌سازی کاربردی فراخوانی شوند گنجانده شده باشد.
این مراحل را دنبال کنید:
در کنسول Google Cloud، پانل میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات کاربری را باز کنید.
کلید میانای API (کلید میانای برنامه‌سازی کاربردی) را که برنامه‌تان برای استفاده از آن پیکربندی شده است انتخاب کنید (برای مثال، «کلید iOS» برای برنامه iOS).
در صفحه ویرایش کلید میانای برنامه‌سازی کاربردی، بخش محدودیت‌های میانای برنامه‌سازی کاربردی را پیدا کنید.
مطمئن شوید گزینه محدود کردن کلید انتخاب شده باشد. اگر این‌طور نیست، کلید شما نامحدود است و احتمالاً منبع خطا این نیست.
در منوِ کرکره‌ای میاناهای برنامه‌سازی کاربردی انتخاب‌شده، میانای برنامه‌سازی کاربردی 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 4 Argon:
gemini-4-argon - جدیدترین نام مدل 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 Nano Banana 2.1
نام مدل:
gemini-nano-banana-2.1 - جدیدترین Gemini Nano Banana 2
نام مدل:
gemini-3.1-flash-image - جدیدترین نام مدل Gemini Nano Banana 2 Lite:
gemini-3.1-flash-lite-image - جدیدترین نام مدل Gemini Nano Banana Pro:
gemini-3-pro-image
- جدیدترین نام مدل Gemini 4 Argon:
مکان نامعتبر (فقط درصورت استفاده از ارائه‌دهنده 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 4.x و 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 خود را به طرح قیمت‌گذاری Blaze پرداخت به اندازه استفاده ارتقا دهید.
برخی‌از مدل‌ها در Gemini Developer API «سطح رایگان» دردسترس نیستند و به «سطح پولی» نیاز دارند، یعنی پروژه‌تان باید در طرح قیمت‌گذاری Blaze با پرداخت به اندازه استفاده باشد. برای مثال، مدل‌های زیر تقریباً همیشه به صورت‌حساب نیاز دارند:
- اکثر مدل‌های پیش‌نمایش و آزمایشی
- مدل‌های تولید رسانه (مثل مدل‌های Gemini Nano Banana)
برخی‌از مدل‌ها در «رده رایگان» Gemini Developer API ویژگی‌های پایه‌ای ارائه می‌دهند، اما برای استفاده از ویژگی‌های پیشرفته‌تر به «رده پولی» نیاز دارند. برای مثال:
- هنگام استفاده از اکثر مدل‌های Gemini 3.x،
«پشتیبانی با
Google Search یاGoogle Maps » نیاز به صورت‌حساب دارد.
- هنگام استفاده از اکثر مدل‌های Gemini 3.x،
«پشتیبانی با
درباره طرح‌های قیمت‌گذاری Firebase و Gemini Developer API بیشتر بدانید.
برای جزئیات بیشتر، به Gemini Developer API اسناد قیمت‌گذاری و پرسشگان صورت‌حساب مراجعه کنید.