کدهای خطا
هر خطای OneProvider را رمزگشایی کنید: معنی هر کد وضعیت، پیام دقیق، محدودیت‌های زمانی، خطا در میانهٔ استریم و اینکه چه زمانی تلاش مجدد بی‌خطر است.
هر کد وضعیت چه معنایی دارد، دقیقاً چه پیامی می‌بینید و گام بعدی چیست.
همهٔ مدل‌ها، قابلیت‌ها و قیمت‌ها فهرست مستندات برای عامل‌های هوش مصنوعی:https://oneprovider.dev/docs/llms.txt شکل خطا
هر خطا در همهٔ endpointها (/v1/messages، /v1/chat/completions، /v1/responses، /v1/models) یک JSON با همین شکل است. خطای موجودی code هم دارد:
{
"type": "error",
"error": {
"type": "insufficient_balance",
"code": "insufficient_quota",
"message": "Insufficient balance on this API key. Top up: dashboard.oneprovider.dev"
}
}SDKهای OpenAI مثل همیشه error.message را از این بدنه می‌خوانند، پس در هر کلاینت همان متن را می‌بینید.
کدهای وضعیت
| وضعیت | error.type | پیام و معنا | چه کنیم |
|---|---|---|---|
| 400 | invalid_request_error | درخواست ناقص یا نادرست است: JSON نامعتبر، فیلدی که جا افتاده یا مقداری که مجاز نیست. پیام، مشکل را نام می‌برد. | آنچه را پیام نشان می‌دهد اصلاح کنید و دوباره بفرستید. ارسال دوبارهٔ بدون تغییر همان خطا را برمی‌گرداند. |
| 400 | invalid_request_error | prompt is too long: N tokens > M maximum ورودی از پنجرهٔ زمینهٔ این مدل بزرگ‌تر است. N و M به مدل بستگی دارند. | تاریخچه یا پیوست‌ها را کوتاه کنید یا مدلی با زمینهٔ بزرگ‌تر انتخاب کنید. Claude Code وقتی این خطا را ببیند گفت‌وگو را خودش فشرده می‌کند. |
| 400 | invalid_request_error | Model X is not available on this API key بستهٔ کلید شما این مدل را شامل نمی‌شود. | مدلی را انتخاب کنید که GET /v1/models یا صفحهٔ قیمت‌ها فهرست کرده است. |
| 401 | authentication_error | Invalid API key API key is required کلید ارسال نشده، اشتباه تایپ شده یا در هدر نادرست فرستاده شده است. | کلید خام sk-… را بدون گیومه و فاصله در x-api-key یا Authorization: Bearer بفرستید. |
| 401 | authentication_error | API key is disabled کلید غیرفعال است یا حساب فعال نیست. | کلید را در حساب کاربری (صفحهٔ «کلیدها») بررسی کنید یا به @Oneproviderhelpbot پیام بدهید. |
| 403 | permission_error | API key expired کلید از تاریخ انقضای خود گذشته است. | کلید را تمدید کنید یا در حساب کاربری (صفحهٔ «کلیدها») کلید جدید صادر کنید. |
| 404 | not_found_error | The requested API endpoint does not exist معمولاً base URL نادرست است، مثلاً /v1/v1 در مسیر. | Claude Code و SDKهای Anthropic: https://api.oneprovider.dev. SDKهای OpenAI و کلاینت‌های سازگار با OpenAI: https://api.oneprovider.dev/v1. |
| 413 | invalid_request_error | request body exceeds size limit بدنهٔ درخواست بزرگ‌تر از 32 MB است. | تصاویر و فایل‌های کوچک‌تر یا کمتری بفرستید، یا کار را به چند درخواست تقسیم کنید. |
| 429 | insufficient_balance | Insufficient balance on this API key. Top up: dashboard.oneprovider.dev موجودی حساب کاربری یا سقف مصرف کلید تمام شده است. بدنه شامل error.code برابر insufficient_quota است و پاسخ هدر x-should-retry: false دارد. | دوباره تلاش نکنید. حساب کاربری را شارژ کنید (ربات یا app.oneprovider.dev) یا سقف کلید را بالا ببرید، سپس درخواست را دوباره بفرستید. |
| 429 | rate_limit_error | Rate limit exceeded; retry later درخواست‌های زیاد در زمان کوتاه. ممکن است هدر Retry-After داشته باشد. | اگر Retry-After هست به همان تعداد ثانیه صبر کنید، وگرنه با وقفهٔ فزاینده دوباره تلاش کنید. اگر ادامه داشت، درخواست‌های موازی کمتری بفرستید. |
| 500, 502 | server_error | Service temporarily unavailable; retry later یک خرابی موقت از سمت ما. | با وقفهٔ فزاینده دوباره تلاش کنید. |
| 503 | server_error | Temporary provider issue on our side, retry in a minute Service temporarily unavailable; retry later موقت است. مشکلی در کلید یا درخواست شما نیست. | با وقفهٔ فزاینده دوباره تلاش کنید؛ معمولاً ظرف یک دقیقه برطرف می‌شود. |
| 504 | server_error | Service timed out; retry later درخواست از محدودیت زمانی گذشت (پایین‌تر را ببینید). | دوباره تلاش کنید. برای پاسخ‌های طولانی stream: true را روشن کنید. |
محدودیت‌های زمانی
- یک درخواست بدون استریم باید حداکثر ظرف 6 دقیقه شروع به پاسخ دادن کند.
- هر درخواستی، از جمله استریم، حداکثر 10 دقیقه زمان دارد.
- برای تولیدهای طولانی از
stream: trueاستفاده کنید: استریم بلافاصله شروع به پاسخ می‌کند. اگر یک پاسخ بیش از 10 دقیقه لازم دارد، کار را تقسیم کنید.
خطاهای درون استریم
وقتی استریم شروع شد، وضعیت از قبل 200 است، پس خطا به صورت یک رویداد می‌رسد. Messages API یک فریم event: error با همان بدنهٔ خطا می‌فرستد؛ Responses API یک رویداد response.failed با دلیل در response.error می‌فرستد.
event: error
data: {"type":"error","error":{"type":"server_error","message":"Service temporarily unavailable; retry later"}}مثل کد وضعیت متناظر با آن برخورد کنید. بخشی از پاسخ که رسیده کامل نیست: اگر برای این خطا تلاش دوباره مجاز است، کل درخواست را دوباره بفرستید.
چه زمانی دوباره تلاش کنیم
- اول اصلاح کنید، تلاش دوباره نکنید: 400، 401، 403، 404، 413 و 429 با
insufficient_balance. تا وقتی درخواست، کلید یا موجودی را عوض نکنید، همان درخواست به همان شکل شکست می‌خورد. - با وقفهٔ فزاینده دوباره تلاش کنید: 429
rate_limit_error، 500، 502، 503، 504. مثلاً 1 ثانیه، 2 ثانیه، 4 ثانیه و همین‌طور تا یک دقیقه، با کمی jitter تصادفی. اگرRetry-Afterهست، دست‌کم به همان اندازه صبر کنید. - به
x-should-retry: falseاحترام بگذارید. SDKهای رسمی Anthropic و OpenAI از قبل این کار را می‌کنند، پس خطای موجودی را دوباره تلاش نمی‌کنند. - با
GET /v1/dashboard/balanceبررسی کنید چه مقدار مانده؛ به مصرف و صورت‌حساب نگاه کنید.
کلاینت‌های رایج چگونه واکنش نشان می‌دهند
- Claude Code. پیام را در جلسه نشان می‌دهد. پس از 401، Claude Code نسخهٔ 2.1.231 و جدیدتر کلید ذخیره‌شده را پاک می‌کند: کلید و base URL (https://api.oneprovider.dev، بدون /v1) را بررسی کنید و کلید را دوباره تنظیم کنید. در خطای موجودی فوراً متوقف می‌شود: شارژ کنید و ادامه دهید. در «prompt is too long» گفت‌وگو را خودش فشرده می‌کند. برای خطاهای موقت 429 و 5xx خودش به‌طور خودکار دوباره تلاش می‌کند.
- Cursor. متن خطا را در گفت‌وگو نشان می‌دهد. کلید API و base URL برابر https://api.oneprovider.dev/v1 را در تنظیمات مدل بررسی کنید، اگر پیام دربارهٔ موجودی است شارژ کنید، سپس دوباره بفرستید.
- Codex. خطای موجودی را به صورت «Quota exceeded» نشان می‌دهد و متوقف می‌شود: شارژ کنید و دستور را دوباره اجرا کنید. خطاهای موقت را ابتدا خودش دوباره تلاش می‌کند.
- Cline. خطا را در وظیفه با دکمهٔ Retry (تلاش دوباره) نشان می‌دهد. ابتدا کلید، base URL یا موجودی را درست کنید، سپس Retry را بزنید.
- Continue. متن خطا را در پنل گفت‌وگو نشان می‌دهد. علت را برطرف کنید و پیام را دوباره بفرستید.