خطاهای API

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

کدهای خطای HTTP

جدول زیر کدهای خطای رایج در بک‌اند، توضیحات مربوط به علل آنها و راه‌حل‌های پیشنهادی را فهرست می‌کند:

کد HTTP وضعیت توضیحات مثال راه حل
۴۰۰ آرگومان نامعتبر بدنه درخواست ناقص است. در درخواست شما اشتباه تایپی وجود دارد یا فیلد الزامی از قلم افتاده است. برای اطلاع از قالب درخواست، مثال‌ها و نسخه‌های پشتیبانی‌شده ، مرجع API را بررسی کنید. استفاده از ویژگی‌های نسخه جدیدتر API با یک نقطه پایانی قدیمی‌تر می‌تواند باعث خطا شود.
۴۰۰ پیش‌شرط ناموفق سطح رایگان API جمینی در کشور شما در دسترس نیست. لطفاً امکان پرداخت هزینه را برای پروژه خود در Google AI Studio فعال کنید. شما در منطقه‌ای درخواست می‌دهید که سطح رایگان پشتیبانی نمی‌شود و پرداخت هزینه را برای پروژه خود در Google AI Studio فعال نکرده‌اید. برای استفاده از رابط برنامه‌نویسی کاربردی (API) جمینی، باید با استفاده از Google AI Studio یک طرح پولی راه‌اندازی کنید.
۴۰۳ مجوز_رد_شد کلید API شما مجوزهای لازم را ندارد. شما از کلید API اشتباه استفاده می‌کنید؛ شما سعی دارید از یک مدل تنظیم‌شده بدون احراز هویت مناسب استفاده کنید. بررسی کنید که کلید API شما تنظیم شده باشد و دسترسی لازم را داشته باشد. و مطمئن شوید که برای استفاده از مدل‌های تنظیم‌شده، احراز هویت مناسبی را انجام می‌دهید.
۴۰۴ یافت نشد منبع مورد نظر یافت نشد. فایل تصویری، صوتی یا ویدیویی که در درخواست شما به آن اشاره شده باشد، یافت نشد. بررسی کنید که آیا تمام پارامترهای درخواست شما برای نسخه API شما معتبر هستند یا خیر.
۴۲۹ منابع_تمام_شده شما از یکی از محدودیت‌های نرخ API (RPM، TPM، RPD، هزینه و غیره) فراتر رفته‌اید. شما درخواست‌های زیادی ارسال می‌کنید، از توکن‌های زیادی استفاده می‌کنید، یا از محدودیت‌های هزینه‌ای برای سابقه و سطح صورتحساب حساب خود فراتر می‌روید. تأیید کنید که در محدوده نرخ مدل هستید. صبر کنید و پس از مدت کوتاهی دوباره امتحان کنید. نرخ یا اندازه درخواست‌های خود را کاهش دهید. در صورت نیاز، درخواست افزایش نرخ را بدهید .
۴۹۹ لغو شد عملیات، معمولاً توسط تماس‌گیرنده، لغو می‌شد. کلاینت قبل از اینکه API بتواند پاسخ خود را تمام کند، اتصال را قطع کرد. بررسی کنید که آیا کلاینت یا زیرساخت شبکه شما اتصال را زودتر از موعد مقرر قطع می‌کند یا خیر (مثلاً به دلیل وقفه زمانی سمت کلاینت).
۵۰۰ داخلی خطای غیرمنتظره‌ای از طرف گوگل رخ داده است. متن ورودی شما خیلی طولانی است. صفحه وضعیت API Gemini را برای هرگونه حادثه در حال وقوع بررسی کنید. زمینه ورودی خود را کاهش دهید یا موقتاً به مدل دیگری (مثلاً از Gemini 2.5 Pro به Gemini 2.5 Flash) تغییر دهید و ببینید که آیا کار می‌کند یا خیر. یا کمی صبر کنید و درخواست خود را دوباره امتحان کنید. اگر مشکل پس از تلاش مجدد ادامه داشت، لطفاً آن را با استفاده از دکمه ارسال بازخورد در Google AI Studio گزارش دهید.
۵۰۳ غیرقابل دسترس ممکن است سرویس موقتاً دچار اضافه بار یا قطعی باشد. ظرفیت سرویس موقتاً در حال اتمام است. صفحه وضعیت API Gemini را برای هرگونه مشکل جاری بررسی کنید. موقتاً به مدل دیگری (مثلاً از Gemini 2.5 Pro به Gemini 2.5 Flash) تغییر دهید و ببینید که آیا کار می‌کند یا خیر. یا کمی صبر کنید و درخواست خود را دوباره امتحان کنید. اگر مشکل پس از تلاش مجدد همچنان ادامه داشت، لطفاً آن را با استفاده از دکمه ارسال بازخورد در Google AI Studio گزارش دهید.
۵۰۴ مهلت_تمام_شد این سرویس قادر به اتمام پردازش در مهلت مقرر نیست. درخواست (یا متن) شما برای پردازش به موقع، بسیار طولانی است. برای جلوگیری از این خطا، در درخواست کلاینت خود، یک «timeout» بزرگتر تنظیم کنید.

قالب پاسخ خطا

وقتی یک درخواست GenerateContent با شکست مواجه می‌شود، API کد وضعیت HTTP (مانند 400 Bad Request ، 403 Forbidden یا 429 Too Many Requests ) را تنظیم می‌کند و یک بدنه پاسخ JSON حاوی جزئیات وضعیت gRPC را برمی‌گرداند:

{
  "error": {
    "code": 400,
    "message": "API key not valid. Please pass a valid API key.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "API_KEY_INVALID",
        "domain": "googleapis.com",
        "metadata": {
          "service": "generativelanguage.googleapis.com"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "API key not valid. Please pass a valid API key."
      }
    ]
  }
}
میدان نوع توضیحات
code عدد صحیح کد وضعیت HTTP.
message رشته توضیحی خوانا برای انسان از خطا.
status رشته کد وضعیت gRPC در SCREAMING_CASE .
details آرایه زمینه خطای اضافی، مانند ErrorInfo یا LocalizedMessage .

قدم بعدی چیست؟