کدهای خطا

خطای ۴۰۰ : 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 جدید دریافت کنید و سپس آن را که در برنامه شما است جایگزین کنید . فایل/شیء پیکربندی جدید باید حاوی یک کلید 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.

این خطا ناشی از پروژه‌ای است که هنگام فعال بودن رابط برنامه‌نویسی کاربردی Vertex AI در پروژه، کارگزارهای خدمات مورد نیاز را به درستی و به صورت خودکار ارائه نکرده است. این یک مشکل شناخته شده در برخی پروژه‌ها است و ما در حال کار بر روی یک راه‌حل جهانی برای آن هستیم.

در اینجا راه حلی برای رفع مشکل پروژه شما و ارائه صحیح این سرویس ایجنت‌ها ارائه شده است تا بتوانید آدرس‌های اینترنتی Cloud Storage for Firebase را در درخواست‌های چندوجهی خود بگنجانید. شما باید مالک پروژه باشید و فقط باید این مجموعه وظایف را یک بار برای پروژه خود انجام دهید.

1. با استفاده از gcloud CLI به آن دسترسی پیدا کنید و احراز هویت کنید.
   ساده‌ترین راه برای انجام این کار از طریق Cloud Shell است. برای اطلاعات بیشتر به مستندات Google Cloud مراجعه کنید.

2. در صورت درخواست، دستورالعمل‌های نمایش داده شده در ترمینال را دنبال کنید تا gcloud CLI روی پروژه Firebase شما اجرا شود.

   شما به شناسه پروژه Firebase خود نیاز دارید که می‌توانید آن را در بالای settings پروژه در کنسول Firebase پیدا کنید.

3. با اجرای دستور زیر، عوامل سرویس مورد نیاز را در پروژه خود فراهم کنید:

   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 ''
   

4. چند دقیقه صبر کنید تا از آماده‌سازی سرویس‌ها مطمئن شوید و سپس دوباره درخواست چندوجهی خود را که شامل آدرس اینترنتی Cloud Storage for Firebase است، ارسال کنید.

اگر بعد از چند دقیقه انتظار هنوز این خطا را دریافت می‌کنید، با پشتیبانی 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 به‌روزرسانی کنید تا API مورد نیاز را شامل شود. برای Firebase AI Logic ، باید مطمئن شوید که API مربوط به Firebase AI Logic ( firebasevertexai.googleapis.com ) در فهرست APIهای انتخاب‌شده‌ای که می‌توان با استفاده از کلید API فراخوانی کرد، گنجانده شده است.

این مراحل را دنبال کنید:

1. در کنسول Google Cloud ، پنل APIs & Services > Credentials را باز کنید.

2. کلید API که برنامه شما برای استفاده از آن پیکربندی شده است را انتخاب کنید (برای مثال، "کلید iOS" برای یک برنامه iOS).

3. در صفحه ویرایش کلید API ، بخش محدودیت‌های API را پیدا کنید.

4. مطمئن شوید که گزینه Restrict key انتخاب شده باشد. اگر اینطور نیست، کلید شما بدون محدودیت است و احتمالاً این منبع خطا نیست.

5. در منوی کشویی Selected APIs ، عبارت Firebase AI Logic API را جستجو و انتخاب کنید تا به لیست APIهای انتخابی که می‌توان با استفاده از کلید API فراخوانی کرد، اضافه شود.

6. روی ذخیره کلیک کنید.

   اعمال تغییرات ممکن است تا پنج دقیقه طول بکشد.

خطای ۴۰۳ : PERMISSION_DENIED: The caller does not have permission.

اگر خطای ۴۰۳ با متن PERMISSION_DENIED: The caller does not have permission. دریافت کردید، معمولاً به این معنی است که کلید API موجود در فایل/شیء پیکربندی Firebase شما متعلق به یک پروژه Firebase متفاوت است.

بررسی کنید که کلید API فهرست‌شده در فایل/شیء پیکربندی Firebase شما با کلید API برنامه‌تان مطابقت داشته باشد. می‌توانید تمام کلیدهای API خود را در پنل APIها و خدمات > اعتبارنامه‌ها در کنسول Google Cloud مشاهده کنید.

اگر متوجه شدید که آنها مطابقت ندارند، یک فایل/شیء پیکربندی Firebase جدید دریافت کنید و سپس آن را که در برنامه شما است جایگزین کنید . فایل/شیء پیکربندی جدید باید حاوی یک کلید API معتبر برای برنامه و پروژه Firebase شما باشد.

خطای ۴۰۴ : Firebase AI Logic genai config not found

اگر در حال تلاش برای استفاده از API توسعه‌دهنده Gemini هستید و خطای ۴۰۴ با مضمون Firebase AI Logic genai config not found » دریافت می‌کنید، معمولاً به این معنی است که پروژه Firebase شما کلید API معتبر Gemini برای استفاده با SDKهای کلاینت Firebase AI Logic ندارد.

در اینجا محتمل‌ترین علل این خطا آورده شده است:

• شما هنوز پروژه Firebase خود را برای Gemini Developer API تنظیم نکرده‌اید.

  چه باید کرد:
  در کنسول Firebase ، به AI Services > AI Logic بروید. روی Get started کلیک کنید و سپس Gemini Developer API را انتخاب کنید. API را فعال کنید و کنسول پروژه شما را برای Gemini Developer API تنظیم می‌کند. پس از تکمیل گردش کار، دوباره درخواست خود را امتحان کنید.

• اگر اخیراً مراحل راه‌اندازی Firebase AI Logic را در کنسول Firebase طی کرده‌اید، ممکن است کلید API Gemini شما هنوز برای همه سرویس‌های backend مورد نیاز در همه مناطق در دسترس نباشد.

  چه باید کرد:
  چند دقیقه صبر کنید و سپس دوباره درخواست خود را امتحان کنید.

• ممکن است کلید API مربوط به Gemini شما از پروژه Firebase حذف شده باشد.

  چه باید کرد:
  بیاموزید که چگونه کلید API Gemini مورد استفاده توسط 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-pro-image-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 : gemini-3.5-flash
    • نام مدل آخرین مدل Gemini 3.x Flash‑Lite : gemini-3.1-flash-lite
    • آخرین مدل Gemini 3.x Pro Image (معروف به "Nano Banana Pro") با نام مدل: gemini-3-pro-image-preview (فقط در پیش‌نمایش موجود است)
    • آخرین تصویر فلش Gemini 3.x (معروف به "Nano Banana 2") با نام مدل: gemini-3.1-flash-image-preview (فقط در پیش‌نمایش موجود است)
    • آخرین مدل «نانو موز» با نام: gemini-2.5-flash-image

• مکان نامعتبر است (فقط در صورت استفاده از ارائه دهنده API Vertex AI Gemini قابل اجرا است)

  • علت : هر یک از درخواست‌های شما که از API مربوط به Vertex AI Gemini استفاده می‌کنند، باید شامل مکان دسترسی به مدل باشند. ممکن است درخواست شما سعی در دسترسی به مدلی در مکانی داشته باشد که مدل در آن مکان در دسترس نیست.

  • راه حل : مطمئن شوید که درخواست شما سعی در دسترسی به مدلی دارد که در آن موجود است.

    هنگام استفاده از API مربوط به Vertex AI Gemini ، منطق هوش مصنوعی فایربیس به صورت پیش‌فرض روی us-central1 تنظیم می‌شود. با این حال، همه مدل‌ها در us-central1 پشتیبانی نمی‌شوند. این بدان معناست که بسته به مدل، ممکن است لازم باشد هنگام مقداردهی اولیه، مکان خاصی را به طور صریح تنظیم کنید.

    • مدل‌های پیش‌نمایش و آزمایشی Gemini : تنظیم موقعیت مکانی روی global الزامی است (به جز مدل‌های Live API ). همه مدل‌های پیش‌نمایش و آزمایشی Gemini (به جز مدل‌های Live API ) فقط در موقعیت global در دسترس هستند.

    • مدل‌های Gemini 3.x : هنگام استفاده از Firebase AI Logic، تنظیم موقعیت مکانی روی global الزامی است. Firebase AI Logic هنوز از موقعیت‌های مکانی us و eu پشتیبانی نمی‌کند.

    • مدل‌های Gemini 2.5 : تنظیم مکان اختیاری است. اگر مکانی را مشخص نکنید، پیش‌فرض us-central1 است.

    • مدل‌های Gemini Live API : تنظیم مکان اختیاری است. اگر مکانی را مشخص نکنید، پیش‌فرض us-central1 است. توجه داشته باشید که مکان global پشتیبانی نمی‌شود .

  درباره نحوه تعیین مکان دسترسی به مدل (از جمله قطعه کد) بیشتر بدانید.

خطاهای ۴۲۹ : "You exceeded your current quota, please check your plan and billing details" یا "Resource exhausted, please try again later."

خطاهای ۴۲۹ نشان می‌دهند که یا از سهمیه خود فراتر رفته‌اید یا مدلی که به آن دسترسی دارید توسط درخواست‌های افراد دیگر بیش از حد بارگذاری شده است.

اقدامی که باید انجام دهید بستگی به این دارد که آیا از Gemini Developer API یا Vertex AI Gemini API استفاده می‌کنید. برای اطلاعات بیشتر در مورد سهمیه‌ها و نحوه درخواست سهمیه اضافی، به محدودیت‌های نرخ و سهمیه‌ها مراجعه کنید.

اگر از رابط برنامه‌نویسی کاربردی Vertex AI Gemini استفاده می‌کنید، مستندات Google Cloud اطلاعات و راهنمایی‌های بیشتری در مورد خطای کد ۴۲۹ ارائه می‌دهد.