این صفحه مرجعی برای کدهای خطای زیرینه که توسط GenerateContent API برگردانده شده است ارائه می‌دهد، قالب پاسخ خطای gRPC را شرح می‌دهد، و مراحل عیب‌یابی را ارائه می‌دهد.
کدهای خطای HTTP
جدول زیر کدهای خطای رایج باطن، توضیح دلایل آن‌ها، و راه‌حل‌های توصیه‌شده را فهرست می‌کند:
| کد HTTP | وضعیت | شرح | نمونه | راه‌حل |
| ۴۰۰ | INVALID_ARGUMENT | قالب متن درخواست درست نیست. | غلط املایی یا فیلد الزامی واردنشده‌ای در درخواست شما وجود دارد. | برای اطلاع از قالب درخواست، نمونه‌ها، و نسخه‌های پشتیبانی‌شده، مرجع میانای برنامه‌سازی کاربردی را بررسی کنید. استفاده از ویژگی‌های نسخه جدیدتر میانای برنامه‌سازی کاربردی با نقطه پایان قدیمی‌تر می‌تواند باعث بروز خطا شود. |
| ۴۰۰ | FAILED_PRECONDITION | سطح رایگان Gemini API در کشور شما دردسترس نیست. لطفاً صدور صورت‌حساب را در پروژه‌تان در Google AI Studio فعال کنید. | درخواستتان را در منطقه‌ای ارسال می‌کنید که سطح رایگان در آن پشتیبانی نمی‌شود و صورت‌حساب را برای پروژه‌تان در Google AI Studio فعال نکرده‌اید. | برای استفاده از Gemini API، باید بااستفاده از Google AI Studio طرح پولی راه‌اندازی کنید. |
| 402 | RESOURCE_EXHAUSTED | موجودی اعتبار پیش‌پرداخت شما تمام شده است. | اعتبار پیش‌پرداخت حساب صورت‌حساب شما تمام شده است، بنابراین هر کلید میانای برنامه‌سازی کاربردی که به آن حساب صورت‌حساب پیوند داده شده است از کار می‌افتد. | به حساب صورت‌حسابتان اعتبار اضافه کنید یا بار کردن مجدد خودکار را روشن کنید. این درخواست را دوباره امتحان نکنید: تا زمانی که اعتبار اضافه نشود، موفقیت‌آمیز نخواهد بود. |
| 403 | PERMISSION_DENIED | کلید میانای API شما اجازه‌های لازم را ندارد یا دسترسی API پروژه شما محدود شده است. | از کلید میانای برنامه‌سازی کاربردی اشتباه یا لورفته استفاده می‌کنید، پروژه‌تان واجدشرایط سطح رایگان نیست، حساب صورت‌حساب شما مانده بدهی دارد، یا می‌خواهید بدون طی کردن اصالت‌سنجی مناسب از مدل تنظیم‌شده استفاده کنید. | بررسی کنید که کلید میانای برنامه‌سازی کاربردی شما معتبر و فعال باشد، وضعیت صورت‌حساب و سطح پروژه خود را در Google AI Studio تأیید کنید، یا به عیب‌یابی پروژه محدودشده یا غیرقابل‌دسترس مراجعه کنید. |
| 404 | NOT_FOUND | منبع درخواستی پیدا نشد. | فایل تصویر، صدا، یا ویدیویی که در درخواستتان به آن ارجاع داده شده است پیدا نشد. | بررسی کنید که آیا همه پارامترهای درخواست شما برای نسخه میانای برنامه‌سازی کاربردی شما معتبر هستند یا نه. |
| 429 | RESOURCE_EXHAUSTED | از یکی‌از محدودیت‌های نرخ API (درخواست در دقیقه، توکن در دقیقه، درخواست در روز، هزینه، و غیره) فراتر رفته‌اید. | درخواست‌های زیادی ارسال می‌کنید، از نشان‌های زیادی استفاده می‌کنید، یا از محدودیت‌های مبتنی بر هزینه برای سابقه صورت‌حساب و سطح حسابتان فراتر می‌روید. | مطمئن شوید که در محدوده حدود نرخ مدل هستید. صبر کنید و پس‌از مدت کوتاهی دوباره امتحان کنید. نرخ یا اندازه درخواست‌هایتان را کاهش دهید. درصورت نیاز، درخواست افزایش حد نرخ کنید. |
| 499 | لغو شد | عملیات لغو شد، معمولاً توسط تماس‌گیرنده. | قبل‌از اینکه API بتواند پاسخ دادن را تمام کند، کارخواه اتصال را بست. | بررسی کنید که آیا کارخواه یا زیرساخت شبکه شما اتصال را زودتر از موعد می‌بندد (برای مثال، به‌دلیل اتمام مهلت سمت کارخواه). |
| ۵۰۰ | داخلی | خطای غیرمنتظره‌ای از سمت Google روی داد. | بافت ورودی‌تان خیلی طولانی است. | برای اطلاع از هرگونه حادثه درحال وقوع، صفحه وضعیت Gemini API را بررسی کنید. بافت ورودی‌تان را کاهش دهید یا موقتاً به مدل دیگری بروید (مثلاً از Gemini 2.5 Pro به Gemini 2.5 Flash) و ببینید آیا کار می‌کند یا نه. یا کمی صبر کنید و درخواستتان را دوباره امتحان کنید. اگر مشکل پس‌از امتحان مجدد همچنان ادامه داشت، لطفاً آن را بااستفاده از دکمه ارسال بازخورد در Google AI Studio گزارش کنید. |
| ۵۰۳ | دردسترس نیست | ممکن است سرویس موقتاً دچار بار اضافی شده باشد یا خراب باشد. | ظرفیت سرویس موقتاً تمام شده است. | برای اطلاع از هرگونه حادثه درحال وقوع، صفحه وضعیت Gemini API را بررسی کنید. به‌طور موقت به مدل دیگری بروید (مثلاً از Gemini 2.5 Pro به Gemini 2.5 Flash) و ببینید آیا کار می‌کند یا نه. یا کمی صبر کنید و درخواستتان را دوباره امتحان کنید. اگر مشکل پس‌از امتحان مجدد همچنان ادامه داشت، لطفاً آن را بااستفاده از دکمه ارسال بازخورد در Google AI Studio گزارش کنید. |
| 504 | DEADLINE_EXCEEDED | سرویس نمی‌تواند پردازش را در مهلت مقرر به‌پایان برساند. | پیام‌واره (یا بافت) شما بزرگ‌تر از آن است که به‌موقع پردازش شود. | برای جلوگیری از این خطا، «زمان اتمام» بزرگ‌تری در درخواست کارخواهتان تنظیم کنید. |
قالب پاسخ خطا
وقتی درخواست 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. |
قدم بعدی چیست
- عیب‌یابی API: حل مشکلات رایج و سناریوهای خطا.
- حدود نرخ: درباره حدود درخواست و مدیریت سهمیه بیشتر بدانید.