خطاها و پیام‌ها

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

ساختار پاسخ خطا

json

1{
2  "error": {
3    "code": "insufficient_credits",
4    "message": "اعتبار کافی نیست. اعتبار مورد نیاز: 8، اعتبار فعلی: 2."
5  }
6}

کدهای رایج

HTTP	Code	توضیح
401	missing_authorization	هدر Authorization ارسال نشده است
401	invalid_api_key	کلید API نامعتبر است
403	revoked_api_key	کلید API لغو شده است
403	insufficient_credits	اعتبار کافی نیست
429	rate_limit_exceeded	تعداد درخواست‌ها از سقف مجاز در دقیقه بیشتر است (پیش‌فرض 30)
404	task_not_found	وظیفه پیدا نشد
400	invalid_request	اطلاعات ارسال‌شده معتبر نیست
400	invalid_idempotency_key	مقدار Idempotency-Key نامعتبر است
409	idempotency_key_in_progress	درخواست مرتبط با این Idempotency-Key هنوز در حال اجراست؛ کمی بعد دوباره تلاش کنید
422	idempotency_key_reused	همان Idempotency-Key با بدنهٔ متفاوت استفاده شده است
500	internal_error	خطای داخلی سرور

محدودیت نرخ درخواست (429)

نرخ درخواست هر کلید در یک بازه ۶۰ ثانیه‌ای محدود می‌شود. سقف فعلی برای پلن‌های کاوشگر و خلاق 30 درخواست/دقیقه، برای استودیو 60 و برای اولترا 120 است. جدول کامل در معرفی API آمده است.

json

1{
2  "error": {
3    "code": "rate_limit_exceeded",
4    "message": "Rate limit exceeded. Maximum 30 requests per minute."
5  }
6}

پاسخ HTTP: 429
هدر Retry-After: چند ثانیه تا دسترسی دوباره به سهمیه
هدر X-RateLimit-Limit: سقف درخواست در دقیقه برای پلن شما
درخواست اجرا نمی‌شود و اعتباری از حساب کم نخواهد شد

نکته

پس از دریافت پاسخ 429، به مدت مشخص‌شده در Retry-After صبر کنید و درخواست را با وقفه افزایشی دوباره بفرستید. برای جلوگیری از پر شدن سریع سهمیه، وضعیت وظیفه را هر ۳ تا ۵ ثانیه بررسی کنید.

جزئیات بیشتر

اگر کلید API ارسال نشده باشد یا کلید نامعتبر یا لغوشده باشد، درخواست رد می‌شود. پیش از ارسال، مطمئن شوید هدر Authorization به‌درستی تنظیم شده و کلید همچنان فعال است.

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

خطای 400 معمولاً نشان‌دهنده وجود فیلدهای نامعتبر است. خطای 404 یعنی وظیفه پیدا نشده است. اگر درخواست مرتبط با Idempotency-Key همچنان در حال اجرا باشد، کد idempotency_key_in_progress (409) را دریافت می‌کنید. استفاده از همان کلید با بدنه متفاوت، کد idempotency_key_reused (422) را برمی‌گرداند. خطای 500 نشان‌دهنده خطای داخلی سرور است؛ کمی بعد دوباره تلاش کنید.