کدهای خطا

خطای ۴۰۰ : 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 ، به صفحه Firebase 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.1 Pro، gemini-3.1-pro-preview است.
    • نام مدل پیش‌نمایش Gemini 3 Flash، gemini-3-flash-preview است.
    • نام مدل پیش‌نمایش «نانو موز پرو» gemini-3-pro-image-preview است.
    • نام مدل پیش‌نمایش «نانو موز ۲» gemini-3.1-flash-image-preview است.
    • نام مدل «نانو موز» gemini-2.5-flash-image است.

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

  • علت : شما از یک نسخه پیش‌نمایش یا آزمایشی از یک مدل (مثلاً gemini-3.1-pro-preview و gemini-3.1-flash-image-preview ) استفاده می‌کنید و موقعیت مکانی global را مشخص نکرده‌اید.

    اگر از API مربوط به Vertex AI Gemini استفاده می‌کنید، تمام مدل‌های پیش‌نمایش و آزمایشی Gemini (به جز مدل‌های Gemini Live) فقط در موقعیت global در دسترس هستند. با این حال، از آنجایی که Firebase AI Logic به طور پیش‌فرض روی برای موقعیت مکانی us-central1 ، هنگام استفاده از این مدل‌های پیش‌نمایش و آزمایشی Gemini ، باید هنگام مقداردهی اولیه سرویس backend API مربوط به Vertex AI Gemini در کد خود، موقعیت مکانی global را به صراحت مشخص کنید.

  • راه حل : هنگام مقداردهی اولیه سرویس Vertex AI Gemini API ، مکان را global مشخص کنید. درباره نحوه تعیین مکان برای دسترسی به مدل (از جمله قطعه کدها) بیشتر بیاموزید.

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

  • دلیل : شما از مدلی استفاده می‌کنید که در مکانی که می‌خواهید به آن دسترسی پیدا کنید، پشتیبانی نمی‌شود.

    اگر از API مربوط به Vertex AI Gemini استفاده می‌کنید، برخی از مدل‌ها فقط در مکان‌های خاصی در دسترس هستند . برای مثال (اما نه به طور کامل):

    • مدل‌های Imagen در موقعیت global پشتیبانی نمی‌شوند .
    • مدل‌های Gemini Live API (مانند gemini-2.0-flash-live-preview-04-09 ) فقط در ... پشتیبانی می‌شوند. مکان us-central1 .
    • مدل‌های Gemini 2.5 (مانند gemini-2.5-pro ) فقط در بازارهای global ، ایالات متحده و برخی از بازارهای اروپایی (و گاهی اوقات در سایر نقاط، اگر پروژه شما گزینه‌های ویژه‌ای داشته باشد) موجود هستند.

  • راه حل : هنگام مقداردهی اولیه سرویس Vertex AI Gemini API ، مطمئن شوید که یک مکان پشتیبانی شده برای مدلی که استفاده می‌کنید، مشخص کرده‌اید. درباره نحوه تعیین مکان دسترسی به مدل (از جمله قطعه کدها) و مکان‌های پشتیبانی شده برای مدل‌ها بیشتر بیاموزید.

    توجه داشته باشید که Firebase AI Logic به صورت پیش‌فرض روی مکان us-central1 .

خطاهای ۴۲۹ : "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 اطلاعات و راهنمایی‌های بیشتری در مورد خطای کد ۴۲۹ ارائه می‌دهد.