خطاها | مستندات هویدای

قالب خطا

هر درخواست ناموفق به /v1، با هر کد وضعیتی، یک بدنهٔ JSON با یک شیء error برمی‌گرداند و پاسخ همیشه هدر x-request-id دارد:

JSON

{  "error": {    "message": "'temperature' must be between 0 and 2.",    "type": "invalid_request_error",    "param": "temperature",    "code": "invalid_value",    "request_id": "6f1d0c52-8a0e-4b0f-9d57-3c1a7a2f4e10"  }}

فیلد	معنی
`code`	دلیل پایدار و قابل پردازش با کد. منطق برنامه را روی این فیلد بنویسید.
`type`	دستهٔ خطا: `invalid_request_error` (درخواست شما ایراد دارد)، `authentication_error` (کلید)، `insufficient_quota` (اعتبار)، `permission_error` (طرح یا محتوا)، `rate_limit_error` (درخواست زیاد) یا `api_error` (مشکل از سمت ما یا مدل).
`message`	جمله‌ای برای خواندن انسان، به انگلیسی. ممکن است بازنویسی شود؛ هرگز برنامه را به متن آن وابسته نکنید.
`param`	فیلد درخواستی که باعث خطا شده، مثل `model` یا `messages`؛ در غیر این صورت `null`.
`request_id`	شناسهٔ همین تماس؛ مقدارش با هدر `x-request-id` یکی است.

بعضی خطاها یک فیلد اضافه دارند: wallet_balance_units در 402 (موجودی شما)، quota_code در quota_exceeded و suggested_models در model_does_not_support_images.

سه پاسخ نمونهٔ دیگر:

JSON

{"error": {"message": "Missing credentials. Send 'Authorization: Bearer <your Hoveydai API key>'.", "type": "authentication_error", "param": null, "code": "invalid_api_key", "request_id": "..."}}

JSON

{"error": {"message": "Rate limit reached (60 per minute). Retry after 3 seconds.", "type": "rate_limit_error", "param": null, "code": "rate_limit_exceeded", "request_id": "..."}}

JSON

{"error": {"message": "The model is temporarily unavailable or busy. Please retry shortly.", "type": "api_error", "param": null, "code": "model_unavailable", "request_id": "..."}}

همهٔ کدهای خطا

وضعیت	کد	چه اتفاقی افتاده	علت معمول	چه کنید
`400`	`invalid_json`	بدنه به‌عنوان شیء JSON خوانده نشد.	بدنهٔ خالی، ویرگول اضافه در انتها، یا متنی که JSON نیست.	بدنه را با `jq .` بررسی کنید و `Content-Type: application/json` بفرستید.
`400`	`missing_required_parameter`	یک فیلد الزامی نیست.	`model`، `messages` یا `role` و `content` یکی از پیام‌ها فرستاده نشده است.	فیلدی را که در `param` آمده اضافه کنید.
`400`	`invalid_type`	نوع یک فیلد درست نیست.	مثلاً `messages` یک رشته است یا `stream` به‌جای `true` مقدار `"true"` دارد.	همان نوعی را بفرستید که `message` می‌خواهد.
`400`	`invalid_value`	فیلد هست، اما مقدارش مجاز نیست.	`temperature` بیرون از ۰ تا ۲، `top_p` بیرون از ۰ تا ۱، فهرست خالی `messages` یا بیش از ۴ رشته در `stop`.	مقدار را در بازهٔ گفته‌شده در `message` بگذارید.
`400`	`unsupported_value`	مقدار در کل معتبر است، اما اینجا پشتیبانی نمی‌شود.	`n` غیر از ۱، یا نقشی غیر از `system`، `developer`، `user` و `assistant`.	`n: 1` و یکی از نقش‌های پشتیبانی‌شده را بفرستید.
`400`	`invalid_image_url`	یکی از بخش‌های تصویر قابل استفاده نیست.	نشانی `http(s)`، base64 خراب، فایل بزرگ‌تر از ۲۰ مگابایت، یا قالبی غیر از PNG، JPEG، WebP و GIF.	تصویر را درون خود درخواست به‌شکل `data:image/png;base64,...` و در همین محدودیت‌ها بفرستید.
`400`	`too_many_images`	درخواست بیش از ۸ تصویر دارد.	بخش‌های `image_url` زیاد در یک درخواست.	تصویرها را در چند درخواست پخش کنید.
`401`	`invalid_api_key`	کلید نیست، نادرست است یا حذف شده.	هدر `Authorization` نیامده، غلط تایپی، یا کلیدی که حذفش کرده‌اید.	`Authorization: Bearer hvd_...` را با کلیدی بفرستید که در بخش «کلیدها»ی پنل هست.
`401`	`token_expired`	توکن نشست پنل منقضی شده.	فراخوانی API با توکن ورود به‌جای کلید.	از کلید API استفاده کنید یا دوباره وارد شوید.
`401`	`session_revoked`	نشست پنل خارج شده است.	خروج از جای دیگر توکن را باطل کرده.	از کلید API استفاده کنید یا دوباره وارد شوید.
`402`	`insufficient_credits`	موجودی کیف پول برای این درخواست کافی نیست.	مدل پولی است و کیف پول خالی است (مدل‌های رایگان هرگز به موجودی نیاز ندارند).	کیف پول را شارژ یا طرح را ارتقا دهید؛ `wallet_balance_units` موجودی باقی‌مانده را نشان می‌دهد.
`402`	`quota_exceeded`	به یکی از سقف‌های طرح رسیده‌اید.	سهمیهٔ روزانه یا ماهانهٔ تصویر؛ `quota_code` می‌گوید کدام.	منتظر بازنشانی سقف بمانید یا طرح را ارتقا دهید.
`403`	`model_requires_paid_plan`	این مدل در طرح شما نیست.	طرح رایگان که مدلی ویژهٔ طرح پولی را صدا زده.	مدل دیگری انتخاب کنید، طرح را ارتقا دهید یا کیف پول را شارژ کنید.
`403`	`content_blocked`	فیلتر محتوای مدل درخواست را رد کرد.	متن یا فایل درخواست فیلتر را فعال کرده.	ورودی را تغییر دهید؛ فرستادن دوبارهٔ همان درخواست همان نتیجه را می‌دهد.
`404`	`model_not_found`	چنین مدلی برای شما وجود ندارد.	غلط تایپی در `model`، مدلی که از فهرست رفته، یا مدلی که به آن دسترسی ندارید.	شناسه را از `GET /v1/models` کپی کنید یا `auto` بگذارید.
`404`	`unknown_url`	چنین نشانی‌ای زیر `/v1` نیست.	مسیر اشتباه، مثل `/v1/embeddings`.	از `POST /v1/chat/completions` یا `GET /v1/models` استفاده کنید.
`405`	`method_not_allowed`	مسیر هست، اما با این متد HTTP نه.	مثلاً `GET` روی `/v1/chat/completions`.	متدی را بزنید که در هدر `Allow` پاسخ آمده است.
`413`	`request_too_large`	بدنه از ۴۰ مگابایت بزرگ‌تر است.	تصویرهای base64 حجیم.	تصویرها را کوچک یا حذف کنید، یا پیام‌های کمتری بفرستید.
`422`	`context_length_exceeded`	ورودی و خروجی درخواستی در پنجرهٔ زمینهٔ مدل جا نمی‌شوند.	تاریخچهٔ طولانی یا `max_tokens` بزرگ.	پیام‌های قدیمی را کم کنید، ورودی را کوتاه کنید یا `max_tokens` را کاهش دهید.
`422`	`model_does_not_support_images`	مدل تصویر نمی‌خواند.	بخش `image_url` برای مدلی فقط‌متنی فرستاده شده.	مدلی از `suggested_models` یا مدلی با `supports_vision` در `/v1/models` بردارید.
`429`	`rate_limit_exceeded`	کلید شما از سقف درخواست در دقیقه بیشتر فرستاده است.	حلقه یا هجوم ناگهانی؛ سقف پیش‌فرض ۶۰ درخواست در دقیقه برای هر کلید است.	به اندازهٔ `Retry-After` ثانیه صبر و دوباره تلاش کنید؛ درخواست‌ها را پخش کنید.
`429`	`too_many_concurrent`	هم‌زمان درخواست‌های زیادی از شما در حال اجراست.	پیش‌فرض: ۲ درخواست هم‌زمان در طرح رایگان و ۴ در طرح‌های پولی.	منتظر پایان یکی بمانید یا بعد از `Retry-After` دوباره بفرستید.
`500`	`internal_error`	در هویدای خطایی رخ داده است.	ایرادی در سمت ما.	یک بار دوباره بفرستید؛ اگر تکرار شد با `request_id` به پشتیبانی بنویسید.
`502`	`provider_error`	ارائه‌دهندهٔ مدل خطا داد یا پاسخ خالی برگرداند.	خطا در سمت بالادستی.	با فاصلهٔ فزاینده دوباره امتحان کنید؛ اگر ادامه داشت به پشتیبانی بنویسید.
`503`	`model_unavailable`	مدل شلوغ است یا موقتاً در دسترس نیست.	فشار زیاد روی ارائه‌دهنده.	بعد از `Retry-After` دوباره بفرستید یا مدل دیگری بگیرید.
`503`	`service_unavailable`	سرویس فعلاً درخواست نمی‌پذیرد.	فهرست مدل‌ها هنوز آماده نیست یا سمت ارائه‌دهنده در حال رفع مشکل است.	بعد از `Retry-After` دوباره بفرستید.
`504`	`provider_timeout`	مدل دیر پاسخ داد.	پاسخ بلند یا ارائه‌دهندهٔ کند.	دوباره بفرستید، پاسخ کوتاه‌تر بخواهید یا `stream: true` بگذارید.

کدام خطاها را دوباره بفرستیم

فقط 429، 502، 503 و 504 را دوباره بفرستید. هر 4xx دیگر تا وقتی درخواست را عوض نکنید همان خطا را می‌دهد و برای 500 حداکثر یک بار تلاش کافی است.

اگر پاسخ هدر Retry-After دارد، همان‌قدر ثانیه صبر کنید. این هدر در 429 و 503 هست.
در غیر این صورت ۱ ثانیه، بعد ۲، ۴ و ۸ ثانیه صبر کنید و بعد از ۴ یا ۵ تلاش دست بکشید. کمی تصادفی‌بودن اضافه کنید تا کلاینت‌های زیاد هم‌زمان دوباره نفرستند.

for wait in 1 2 4 8; do  code=$(curl -s -o reply.json -w "%{http_code}" https://api.hoveydai.ir/v1/chat/completions \    -H "Authorization: Bearer $HOVEYDAI_API_KEY" -H "Content-Type: application/json" \    -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello"}]}')  case $code in 429|502|503|504) sleep $wait ;; *) break ;; esacdonecat reply.json

خطا در پاسخ استریم

رفتار به این بستگی دارد که خطا چه زمانی رخ دهد:

پیش از اولین قطعه (کلید نادرست، مدل ناشناخته، نبود اعتبار، یا ارائه‌دهنده‌ای که بلافاصله خطا می‌دهد): یک خطای HTTP معمولی با همان کد وضعیت و بدنهٔ JSON بالا می‌گیرید. مثل درخواست بدون stream با آن برخورد کنید.
پس از اولین قطعه: کد وضعیت از قبل 200 فرستاده شده، پس خطا به‌شکل یک رویداد دیگر به‌صورت data: {"error": {...}} با همان فیلدها می‌رسد و استریم بدون data: [DONE] تمام می‌شود. متنی را که تا آن لحظه گرفته‌اید نگه دارید، هر رویداد را از نظر وجود کلید error بررسی کنید و تصمیم بگیرید کل درخواست را دوباره بفرستید یا نه.

اگر ارتباط بدون رویداد خطا هم قطع شود، پاسخ ناتمام است: استریم فقط بعد از data: [DONE] کامل شده است.

هدرهای محدودیت درخواست

پاسخ‌های کلیدی که محدودیت درخواست دارد این هدرها را دارند و اسکریپت مرورگر هم می‌تواند آن‌ها را بخواند:

هدر	معنی
`x-ratelimit-limit-requests`	تعداد درخواست مجاز در پنجرهٔ فعلی.
`x-ratelimit-remaining-requests`	تعداد باقی‌مانده در همین پنجره.
`x-ratelimit-reset-requests`	زمان تا بازنشانی پنجره، مثل `42s`.
`Retry-After`	در `429` و `503`: ثانیه‌هایی که باید تا تلاش بعدی صبر کنید.

ممکن است در بعضی استقرارها هدرهای x-ratelimit-* نباشند؛ به آن‌ها تکیه نکنید و به 429 و Retry-After اعتماد کنید.

چه چیزی را برای پشتیبانی بفرستید

به support@hoveydai.ir بنویسید و این‌ها را بیاورید:

request_id از بدنهٔ خطا یا هدر x-request-id؛ با آن همان تماس را پیدا می‌کنیم.
زمان تماس و منطقهٔ زمانی شما.
شناسهٔ model که استفاده کردید.
کد وضعیت و code دریافتی. هرگز کلید API را ننویسید.