مرجع خطاها
ابتدا HTTP status و error.code، سپس ساختار مخصوص پروتکل.
راهنمای اتصال مشتریان
curl · Python · JavaScript
الگوی پردازش خطا
خطاهای پیش از ارسال به مدل، از جمله احراز هویت، محدودیت دسترسی یا اعتبار، ممکن است در هر سه مسیر قالب مشترک زیر را داشته باشند. بعضی خطاهای ارائهدهنده قالب بومی یا پیام متفاوت دارند. به متن message بهعنوان شناسه ثابت خطا تکیه نکنید.
JSON · ساختار نمایشی
{
"error": {
"message": "Illustrative error message",
"type": "one_hub_error",
"code": "EXAMPLE_ERROR_CODE"
}
}وضعیتها و اقدام مناسب
| HTTP / کد | تفسیر و اقدام |
|---|---|
| 400 | JSON، پارامتر، action یا طول ورودی را با مدل تطبیق دهید؛ retry بدون اصلاح مفید نیست. |
| 401 | کلید نامعتبر، منقضی، غیرفعال یا بودجه کلید پایانیافته؛ وضعیت کلید را در پنل بررسی کنید. |
| 402 · insufficient_toman_quota | اعتبار قابل استفاده برای رزرو درخواست کافی نیست؛ اعتبار و درخواستهای همزمان را بررسی کنید. |
| 403 | IP، گروه، مدل یا مجوز عملیات را بررسی کنید. |
| 403 · toman_api_not_offered | این عملیات در دامنه دسترسی مالی حساب ارائه نشده است؛ مسیر و مجوز حساب را با پشتیبانی بررسی کنید. تغییر کلید بهتنهایی این مجوز را ایجاد نمیکند. |
| 404 · model_not_found | مدل یا مسیر اشتباه است یا برای این عملیات مسیر قابل استفادهای ندارد. |
| 429 | محدودیت نرخ؛ همزمانی را کاهش دهید و Retry-After را در صورت وجود رعایت کنید. |
| 5xx / 503 | خطای سرویس یا ارائهدهنده؛ وضعیت، کد و شناسه درخواست را ثبت و retry محدود اعمال کنید. |
| timeout / قطع جریان | تکمیل پاسخ نامشخص است؛ احتمال مصرف را پیش از ارسال مجدد در نظر بگیرید. |
راهبرد مدیریت خطا
- برای HTTP غیرموفق، بدنه را ابتدا بهعنوان متن بخوانید و در صورت امکان JSON آن را parse کنید.
- برای Streaming، خطای JSON قبل از شروع جریان و رویداد error داخل جریان را جدا مدیریت کنید.
- برای 401، 402 و خطاهای مجوز، retry خودکار مداوم انجام ندهید.
- برای خطاهای گذرا backoff با سقف تلاش و jitter داشته باشید؛ کلید یا ورودی حساس را لاگ نکنید.