این صفحه عیبیابی کدهای خطای رایج برای کیتهای توسعه نرمافزار 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) خود را در پانل میاناهای برنامهسازی کاربردی (API) و سرویسها > اطلاعات کاربری در کنسول 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 دسترسی به این مدلها را مسدود میکند، مگراینکه درخواستهای شما حاوی یک کد App Check معتبر باشد (که مستلزم آن است که App Check برای Firebase AI Logic اجرا شود).
اگر میخواهید به مدلی که خطا را برگردانده است دسترسی پیدا کنید، کارهای زیر را انجام دهید:
App Check را برای Firebase AI Logic راهاندازی کنید. برای توسعه محلی، مطمئن شوید که App Check ارائهکننده اشکالزدایی را راهاندازی کردهاید.
اگر قبلاً App Check را راهاندازی کردهاید، دوباره بررسی کنید که همه مراحل را در دستورالعملهای پیوندشده تکمیل کرده باشید.
درخواست را از برنامهتان به Firebase AI Logic باز ارسال کنید.
این درخواست همراه با یک کد معتبر App Check ارسال خواهد شد و دیگر خطای ۴۰۳ را دریافت نخواهید کرد.
هنوز خطای ۴۰۳ را دریافت میکنید؟
اگر App Check اجرا شده است و درخواستی ارسال کردهاید اما همچنان خطای ۴۰۳ دریافت میکنید، بررسی کنید که آیا محافظت دربرابر بازپخش برای Firebase AI Logic اجرا شده است یا نه (ازجمله در حالت «فقط نظارت»).
وقتی محافظت دربرابر تکرار اعمال میشود، فقط توکنهای با استفاده محدود بهعنوان تأییدشده برای Firebase AI Logic بهحساب میآیند، یعنی توکنهای جلسه معمولی نمیتوانند این خطای ۴۰۳ را پاک کنند. برای حل این مشکل، یکی از کارهای زیر را انجام دهید:
گزینه ۱: اگر میخواهید از محافظت دربرابر بازپخش استفاده کنید، راهاندازی محافظت دربرابر بازپخش را دوباره بررسی کنید.
مطمئن شوید که همه مراحل راهاندازی محافظت دربرابر بازپخش را تکمیل کردهاید، که شامل فعال کردن توکنهای با استفاده محدود در پایگاه کد برنامهتان میشود.
درخواست را دوباره به Firebase AI Logic ارسال کنید.
گزینه ۲: اگر نمیخواهید از محافظت دربرابر تکرار استفاده کنید یا توکنهای با استفاده محدود را در برنامهتان فعال نکردهاید، میتوانید محافظت دربرابر تکرار را غیرالزامی کنید.
محافظت دربرابر تکرار را در کنسول Firebase لغو کنید: به برگه امنیت > بررسی برنامه > میاناهای برنامهسازی کاربردی بروید، کلیک کنید تا ردیف Firebase AI Logic ازهم باز شود، روی راهاندازی کلیک کنید، و سپس محافظت دربرابر تکرار را در کادر گفتگو لغو کنید.
درخواست را دوباره به Firebase AI Logic ارسال کنید.
قبلاز اینکه برنامهتان را برای کاربران نهایی منتشر کنید، باید ارائهدهنده گواهی تولید راهاندازی کنید (مثل 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 استفاده نکردهاند.
بدون App Check، پروژه شما دربرابر سوءاستفاده از Gemini API آسیبپذیر است. برای کمک به محافظت از پروژه شما، Firebase استفاده از Firebase AI Logic را غیرفعال کرد تا زمانی که درخواستهای شما شامل یک کد معتبر App Check باشد (که مستلزم اجرای App Check برای Firebase AI Logic است).
وقتی آماده بودید دوباره از Firebase AI Logic استفاده کنید، کارهای زیر را انجام دهید:
App Check را برای Firebase AI Logic راهاندازی کنید. برای توسعه محلی، مطمئن شوید که App Check ارائهکننده اشکالزدایی را راهاندازی کردهاید.
اگر قبلاً App Check را راهاندازی کردهاید، دوباره بررسی کنید که همه مراحل را در دستورالعملهای پیوندشده تکمیل کرده باشید.
درخواست را از برنامهتان به Firebase AI Logic باز ارسال کنید.
این درخواست همراه با یک کد معتبر App Check ارسال خواهد شد و دیگر خطای ۴۰۳ را دریافت نخواهید کرد.
هنوز خطای ۴۰۳ را دریافت میکنید؟
اگر App Check اجرا شده است و درخواستی ارسال کردهاید اما همچنان خطای ۴۰۳ دریافت میکنید، بررسی کنید که آیا محافظت دربرابر بازپخش برای Firebase AI Logic اجرا شده است یا نه (ازجمله در حالت «فقط نظارت»).
وقتی محافظت دربرابر تکرار اعمال میشود، فقط توکنهای با استفاده محدود بهعنوان تأییدشده برای Firebase AI Logic بهحساب میآیند، یعنی توکنهای جلسه معمولی نمیتوانند این خطای ۴۰۳ را پاک کنند. برای حل این مشکل، یکی از کارهای زیر را انجام دهید:
گزینه ۱: اگر میخواهید از محافظت دربرابر بازپخش استفاده کنید، راهاندازی محافظت دربرابر بازپخش را دوباره بررسی کنید.
مطمئن شوید که همه مراحل راهاندازی محافظت دربرابر بازپخش را تکمیل کردهاید، که شامل فعال کردن توکنهای با استفاده محدود در پایگاه کد برنامهتان میشود.
درخواست را دوباره به Firebase AI Logic ارسال کنید.
گزینه ۲: اگر نمیخواهید از محافظت دربرابر تکرار استفاده کنید یا توکنهای با استفاده محدود را در برنامهتان فعال نکردهاید، میتوانید محافظت دربرابر تکرار را غیرالزامی کنید.
محافظت دربرابر تکرار را در کنسول Firebase لغو کنید: به برگه امنیت > بررسی برنامه > میاناهای برنامهسازی کاربردی بروید، کلیک کنید تا ردیف 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 دیگری است.
بررسی کنید که کلید میانای برنامهسازی کاربردی (API) فهرستشده در فایل/شیء پیکربندی Firebase با کلید میانای برنامهسازی کاربردی (API) برنامهتان مطابقت داشته باشد. میتوانید همه کلیدهای میانای برنامهسازی کاربردی (API) خود را در پانل میاناهای برنامهسازی کاربردی (API) و سرویسها > اطلاعات کاربری در کنسول Google Cloud مشاهده کنید.
اگر متوجه شدید که مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید، و سپس آن را در برنامه خود جایگزین کنید. فایل/شیء پیکربندی جدید باید حاوی یک کلید میانای برنامهسازی کاربردی معتبر برای برنامه و پروژه Firebase شما باشد.
خطای ۴۰۳: Requests to this API firebasevertexai.googleapis.com ... are blocked.
اگر خطای ۴۰۳ دریافت کردید که میگوید
Requests to this API firebasevertexai.googleapis.com ... are blocked.، معمولاً به این معنی است که کلید API در پیکربندی Firebase در برنامه شما محدودیتهایی دارد که مانع از فراخوانی API موردنیاز میشود.
برای رفع این مشکل، باید محدودیتهای کلید میانای برنامهسازی کاربردی خود را در کنسول Google Cloud بهروز کنید تا میانای برنامهسازی کاربردی موردنیاز را دربرگیرد. برای Firebase AI Logic،
باید مطمئن شوید Firebase AI Logic API
(firebasevertexai.googleapis.com) در فهرست میاناهای برنامهسازی کاربردی انتخابشده
که میتوانند بااستفاده از کلید میانای برنامهسازی کاربردی فراخوانی شوند گنجانده شده باشد.
این مراحل را دنبال کنید:
در کنسول Google Cloud، پانل APIs & Services (میاناهای برنامهسازی کاربردی و سرویسها) > Credentials (اطلاعات کاربری) را باز کنید.
کلید میانای 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 Hydrogen
نام مدل:
gemini-4-hydrogen - جدیدترین Gemini 4 Argon
نام مدل:
gemini-4-argon - جدیدترین Gemini 4 Carbon
نام مدل:
gemini-4-carbon - جدیدترین 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 Hydrogen
نام مدل:
مدل خاموششده (بازنشسته)
علت: مدلی که میخواهید به آن دسترسی پیدا کنید از تاریخ خاموش شدن (بازنشستگی) آن گذشته است و برای همیشه غیرفعال شده است (برای مثال، مدلهای Gemini 2.5 با کاربرد عمومی در Agent Platform Gemini API (formerly Vertex AI)، مدلهای Gemini 2.0، یا مدلهای Imagen).
رفع مشکل: پرسشگان مدلهای منسوخشده و تعطیلشده را بررسی کنید و کدتان را بهروز کنید تا از مدل جایگزین فعال استفاده کند.
مکان نامعتبر (فقط درصورت استفاده از ارائهدهنده Agent Platform Gemini API (formerly Vertex AI) قابلاجرا است)
علت: ممکن است درخواست شما برای دسترسی به مدلی در مکانی باشد که مدل در آنجا دردسترس نیست.
رفع مشکل: مطمئن شوید درخواستتان برای دسترسی به مدل در جایی است که دردسترس است.
هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI)، میتوانید بهطور اختیاری مکانی را برای دسترسی به مدل درطول مقداردهی اولیه مشخص کنید. اگر مکانی را مشخص نکنید، Firebase AI Logic بهطور پیشفرض به مکانهای زیر میرود:
- هنگام استفاده از نحو مقداردهی اولیه «Agent Platform»:
global - هنگام استفاده از نحو مقداردهی اولیه قدیمی «Vertex AI»:
us-central1
اما همه مدلها در این مکانهای پیشفرض پشتیبانی نمیشوند. این یعنی بسته به مدل، ممکن است لازم باشد درطول مقداردهی اولیه، مکان خاصی را بهطور صریح تنظیم کنید.
مدلهای Gemini پیشنمایش و آزمایشی: فقط در مکان
globalدردسترس است.مدلهای پایدار Gemini 4.x و Gemini 3.x: در مکان
globalو اغلب در مکانهایusوeuدردسترس هستند.مدلهای Gemini Live API 2.5: در بسیاری از مکانها دردسترس است، اما در
globalدردسترس نیست. (توجه داشته باشید که مدلهای Gemini 2.5 با کاربرد عمومی برای Agent Platform Gemini API (formerly Vertex AI) خاموش شدهاند.)
- هنگام استفاده از نحو مقداردهی اولیه «Agent Platform»:
درباره نحوه مشخص کردن مکان برای دسترسی به مدل (ازجمله تکهکدها) بیشتر بدانید.
خطاهای ۴۲۹: "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 اسناد قیمتگذاری و پرسشگان صورتحساب مراجعه کنید.