خطاها و عیب‌یابی
شکل خطا، کدهای اصلی و قدم بعدی مناسب.
قرارداد خطا
{"error":{"code":"INVALID_API_KEY","message":"INVALID_API_KEY","request_id":"UUID"}}در منطق برنامه بر code و status تکیه کنید. متن message برای نمایش و عیب‌یابی است و می‌تواند بهتر یا ترجمه شود. X-Request-ID را کنار خطای داخلی برنامهٔ خود ثبت کنید، ولی Authorization را ثبت نکنید.
| کد | HTTP | اقدام |
|---|---|---|
| INVALID_REQUEST / INVALID_JSON | 400 | نوع و مقدار فیلدها و JSON را اصلاح کنید |
| INVALID_API_KEY | 401 | کلید، انقضا و لغو شدن را بررسی کنید |
| INSUFFICIENT_SCOPE | 403 | کلید دارای مجوز لازم بسازید |
| PLAN_REQUIRED | 403 | مدل متناسب طرح یا طرح لازم را انتخاب کنید |
| ACCOUNT_INACTIVE | 403 | وضعیت حساب را از پشتیبانی پیگیری کنید |
| NOT_FOUND | 404 | شناسه و پروژهٔ مالک را بررسی کنید |
| IDEMPOTENCY_CONFLICT | 409 | برای کار متفاوت یک کلید منطقی تازه بسازید |
| REQUEST_ALREADY_ACCEPTED | 409 | شناسهٔ کار قبلی را پیگیری کنید |
| PAYLOAD_TOO_LARGE | 413 | اندازهٔ فایل و بدنه را کاهش دهید |
| RATE_LIMITED / CONCURRENCY_LIMIT | 429 | Retry-After و صف محدود را رعایت کنید |
| INCOMPLETE_STREAM | 502 | جریان کامل نشده؛ وضعیت قبلی را بررسی کنید |
| SERVICE_UNAVAILABLE | 503 | بدون ساخت درخواست تکراری وضعیت را پیگیری کنید |
خطای ارائه‌دهنده
رد محتوا، محدودیت تصویر مرجع، مدل موقتاً ناموجود یا خطای provider می‌تواند از زیرسرویس برسد. کد و پیام دقیق بازگردانده‌شده را نگه دارید. موجود بودن مدل در فهرست به معنی تضمین سلامت همیشگی ارائه‌دهنده نیست.
خطای پس از 200
در SSE ممکن است جریان با HTTP 200 شروع شود و بعد رویداد response.failed برسد. در Work و ویدیو هم 202 فقط پذیرش است. منطق UI باید وضعیت نهایی سرویس را نمایش دهد.
مدل خارج از دسترس
MODEL_UNAVAILABLE یعنی شناسهٔ مدل در مسیر فعلی ارائه‌دهنده عرضه نمی‌شود. به فیلد available در /v1/models مراجعه کنید و مدل دیگری انتخاب کنید. این رد شدن قبل از رزرو اعتبار اتفاق می‌افتد. خطاهای داخل جریان SSE مانند PROVIDER_UNAVAILABLE یا RATE_LIMITED هم با همان کد در پاسخ JSON مسیر استودیو و گزارش درخواست ثبت می‌شوند.
قرارداد API 1.6.0 · تاریخچهٔ تغییرات