کدهای خطا

خطای ۴۰۰ : 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.

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

در اینجا راه حلی برای رفع مشکل پروژه شما و ارائه صحیح این سرویس ایجنت‌ها ارائه شده است تا بتوانید آدرس‌های اینترنتی 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

اگر خطای ۴۰۴ با مضمون Firebase AI Logic genai config not found دریافت کردید، معمولاً به این معنی است که تنظیمات مربوط به فایربیس هوش مصنوعی لاجیک به اشتباه پیکربندی شده یا وجود ندارد.

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

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

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

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

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

خطای ۴۰۴ : مدل « 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 : gemini-3.6-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 (معروف به "Nano Banana 2") با نام مدل: gemini-3.1-flash-image
    • آخرین مدل ایمیج Gemini 3.x Flash‑Lite (معروف به "Nano Banana 2 Lite") با نام: gemini-3.1-flash-lite-image
    • آخرین مدل Gemini 2.5 Flash Image (معروف به "نانو موز") با نام مدل: gemini-2.5-flash-image

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

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

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

    هنگام استفاده از API پلتفرم عامل Gemini (که قبلاً Vertex AI نام داشت) ، می‌توانید به صورت اختیاری مکانی را برای دسترسی به مدل در طول مقداردهی اولیه مشخص کنید. اگر مکانی را مشخص نکنید، Firebase AI Logic به طور پیش‌فرض مکان‌های زیر را در نظر می‌گیرد:

    • هنگام استفاده از سینتکس مقداردهی اولیه "پلتفرم عامل": global
    • هنگام استفاده از سینتکس مقداردهی اولیه قدیمی "Vertex AI": us-central1

    با این حال، همه مدل‌ها در این مکان‌های پیش‌فرض پشتیبانی نمی‌شوند. این بدان معناست که بسته به مدل، ممکن است لازم باشد که هنگام مقداردهی اولیه، مکان خاصی را به طور صریح تعیین کنید.

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

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

    • مدل‌های Gemini 2.5 : در بسیاری از مکان‌ها موجود است .

    • مدل‌های 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 یا رابط برنامه‌نویسی پلتفرم Gemini (که قبلاً Vertex AI نام داشت) استفاده می‌کنید. برای اطلاعات بیشتر در مورد سهمیه‌ها و نحوه درخواست سهمیه اضافی، به محدودیت‌های نرخ و سهمیه‌ها مراجعه کنید.

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