خطاها، محدودیت‌ها و تلاش مجدد

هر Felo API بدنه خطای JSON با یک کد خطای پایدار و یک شناسه درخواست برمی‌گرداند. نخست وضعیت HTTP را بخوانید، سپس کد و بعد message را.

پوشش خطا

پاسخ‌های تولید جاری از وضعیت HTTP به‌عنوان status استفاده می‌کنند:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

برخی نمونه‌های قدیمی endpoint از status: "error" و رشته کد متفاوتی استفاده می‌کنند. بر اساس وضعیت HTTP و code انشعاب بگیرید، نه بر اساس عبارت دقیق message.

کدهای رایج

مرجع‌های endpoint کدهای مخصوص آن endpoint را فهرست می‌کنند. با خطاهای Chat API یا مرجع endpointی که صدا می‌زنید شروع کنید.

endpointهای تولید مدل

POST /api/v1/images/generations و POST /api/v1/videos/generations خطاهای سطح endpoint را در پوشش OpenAI برمی‌گردانند، نه در پوشش بالا:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

شناسه درخواست در سرآیند پاسخ X-Request-Id است، نه در بدنه. درخواست ردشده وظیفه‌ای نمی‌سازد. پس از آنکه وظیفه‌ای وجود دارد، بیشتر شکست‌ها به‌صورت وضعیت وظیفه پایانی در پاسخ 200 می‌آیند، نه خطای HTTP: status را برای failed یا interrupted بررسی کنید، سپس error.message را بخوانید. تولید تصویر و وظایف ناهمگام را ببینید.

شناسه‌های درخواست

بدنه‌های خطای Felo شامل request_id هستند. آن را همراه endpoint، وضعیت HTTP، کد خطا، شناسه مدل و شناسه وظیفه ثبت کنید. هرگز کلید API کامل را ثبت نکنید.

Model API همچنین یک سرآیند اختیاری درخواست X-Request-Id را می‌پذیرد. وقتی یکی می‌فرستید، برای عیب‌یابی بازتاب داده می‌شود و این امکان را می‌دهد گزارش‌های خودتان را با یک درخواست مرتبط کنید. اگر نمی‌فرستید، از request_id برگشتی استفاده کنید.

محدودیت نرخ

/v2/chat تنها endpoint Felo با محدودیت نرخ مستند و اعمال‌شده است:

• برای هر کلید API، پنجره 1 دقیقه‌ای.
• برای هر کاربر، پنجره 1 دقیقه‌ای.
• برای هر کاربر، پنجره 1 ساعته.

کاربران با اشتراک مؤثر پولی Felo، از جمله اشتراک‌های سازمانی، معاف‌اند و سرآیند X-RateLimit-* دریافت نمی‌کنند. اگر وضعیت اشتراک قابل تأیید نباشد، محدودیت‌ها همچنان اعمال می‌شوند.

دیگر endpointهای /v2/** در حال حاضر محدودیت نرخ اعمال‌شده ندارند. درخواست‌های Model API همچنان ممکن است توسط ارائه‌دهنده بالادستی محدود شوند که می‌تواند به‌صورت 429 ظاهر شود.

محدودیت‌های عددی را سخت‌کد نکنید. سرآیندها را در هر پاسخ بخوانید.

سیاست تلاش دوباره

حلقه پیشنهادی:

1. فقط درخواست‌های بی‌اثر یا تکرارپذیر ایمن را دوباره تلاش کنید.
2. از عقب‌نشینی نمایی استفاده کنید: حدود 1 ثانیه شروع کنید، دو برابر کنید و در 30 ثانیه سقف بگذارید.
3. jitter تصادفی اضافه کنید تا کلاینت‌ها هم‌زمان دوباره تلاش نکنند.
4. پس از شمار کمی تلاش متوقف شوید و خطا را نشان دهید.
5. در 429، به‌جای برنامه خودتان به Retry-After احترام بگذارید.

توالی اشکال‌زدایی

1. بررسی کنید کلید وجود دارد و لغو نشده است.
2. با همان کلید GET /api/v1/models را صدا بزنید تا احراز هویت را تأیید کنید.
3. کوچک‌ترین درخواست معتبر را به endpoint هدف بفرستید.
4. جریان‌دهی، ابزارها یا ورودی‌های بزرگ را یکی‌یکی اضافه کنید.
5. برای کار ناهمگام، پیش از ارسال دوباره وضعیت وظیفه را بررسی کنید.

مرتبط

• احراز هویت
• کانال‌ها و مسیریابی ارائه‌دهنده
• وظایف ناهمگام
• عیب‌یابی