رفع خطاهای 401، 403، 429 و 5xx
مشکل‌های API OneProvider را سریع رفع کنید: نشانه، علت و راه‌حل برای 400، 401، 403، 404، 429، 503 و 504، ورود Claude Code، VPN و زمان تماس با پشتیبانی.
دوازده حالت خرابی مشخص که هر هفته می‌بینیم. نشانه ← علت ← راه‌حل یک‌خطی.
همهٔ مدل‌ها، قابلیت‌ها و قیمت‌ها فهرست مستندات برای عامل‌های هوش مصنوعی:https://oneprovider.dev/docs/llms.txt پیش از شروع دستور curl -s https://api.oneprovider.dev/v1/models -H "x-api-key: $ANTHROPIC_API_KEY" را اجرا کنید. اگر فهرست مدل‌های JSON غیرخالی برگرداند، دسترسی شبکه و احراز هویت شما سالم است — هر مشکلی که با آن روبه‌رو هستید مربوط به همان درخواست است، نه زیرساخت. پرسش‌های پرتکرار
آیا باید وارد Claude Code شوم؟ و 401 و «Auth conflict» چیست
نه. کلید OneProvider بدون حساب Claude کار می‌کند. برای Claude Code متغیرهای ANTHROPIC_BASE_URL و ANTHROPIC_AUTH_TOKEN را تنظیم کنید (کلید به صورت Authorization: Bearer فرستاده می‌شود). این متغیر بر ورود ذخیره‌شده و بر متغیرهای دیگر اولویت دارد و پیام تأییدی هم نمی‌خواهد. گیت‌وی ما ANTHROPIC_API_KEY (هدر x-api-key) را هم می‌پذیرد، اما Claude Code در حالت تعاملی یک‌بار از شما می‌خواهد چنین کلیدی را تأیید کنید و کلید ردشده را بی‌صدا نادیده می‌گیرد (دوباره فعال کردن: /config ← Use custom API key).
اگر صفحهٔ ورود، 401 Invalid API key یا Auth conflict را می‌بینید، گام‌به‌گام جلو بروید:
/statusرا اجرا کنید: بایدAnthropic base URLمربوط به OneProvider و یک خطAuth tokenیاAPI keyبا نام متغیر شما نشان دهد. اگر خطLogin methodیک حساب claude.ai را نشان داد، یعنی متغیر به جلسه نرسیده است.Auth conflict(هم ورود claude.ai و هم کلید):/logoutرا اجرا کنید؛ متغیرهای شما می‌مانند.401 Invalid API key: یکANTHROPIC_AUTH_TOKENبیگانه (توکن سرویس دیگر) کلید شما را می‌پوشاند، یا مقدار گیومه یا فاصلهٔ اضافه دارد. آن را برابر کلید کامل OneProvider و بدون گیومه بگذارید.- صفحهٔ ورود می‌ماند با اینکه متغیرها در
.claude/settings.jsonپروژه هستند: آن بلوک بعد از تنظیم اولین اجرا خوانده می‌شود، پس متغیرها را در shell یا در~/.claude/settings.jsonبگذارید.
# macOS / Linux: what is actually set
env | grep -E 'ANTHROPIC_(BASE_URL|AUTH_TOKEN|API_KEY)' | sed -E 's/(sk-.{4}).*/\1.../'
grep -nE 'ANTHROPIC_(AUTH_TOKEN|API_KEY)' ~/.zshrc ~/.bashrc 2>/dev/nullآیا برای Codex CLI باید وارد ChatGPT شوم؟
نه. وقتی ارائه‌دهندهٔ oneprovider در ~/.codex/config.toml فعال باشد (env_key = "ONEPROVIDER_API_KEY")، Codex فقط با کلید کار می‌کند. درخواست ورود به ChatGPT یا «You've hit your usage limit» یعنی ارائه‌دهنده فعال نیست و درخواست به ChatGPT رفته است.
به این ترتیب بررسی کنید: خطوط model_provider و model در همان بالای فایل و بالاتر از هر [table] باشند؛ Codex کاملاً راه‌اندازی دوباره شده و وظیفه تازه باشد؛ کلید در همان ترمینال export شده باشد:
codex logout
export ONEPROVIDER_API_KEY="sk-..."
# quick test without editing the file:
codex -c model_provider=oneproviderراهنمای کامل در صفحهٔ Codex (OpenAI) .
آیا VPN لازم است؟ محدودیت منطقه‌ای هست؟
VPN لازم نیست — OneProvider هیچ محدودیت منطقه‌ای ندارد. endpoint به نام api.oneprovider.dev از سراسر جهان در دسترس است و ترافیک را بر اساس موقعیت جغرافیایی مسدود نمی‌کند.
بدتر اینکه VPN / پروکسی‌های VLESS اغلب اتصال API را از دو راه خراب می‌کنند:
- استریم SSE داخل پروکسی بافر می‌شود — استریم وسط توکن قطع می‌شود.
- مذاکرهٔ HTTP/2 + ALPN در گام‌های رله می‌شکند — کلاینت
connection resetمی‌بیند.
اگر استریم‌های قطع‌شده، connection reset یا timeoutهای تصادفی می‌بینید، VPN / پروکسی VLESS را خاموش کنید و دوباره امتحان کنید. ما از سمت خودمان استریم‌ها را بافر نمی‌کنیم.
خطای JSON parse در تنظیمات (یا یک 429)
شایع‌ترین علت گیومه‌های «هوشمند» (“ ”) در تنظیمات JSON شماست. وقتی از پیام‌رسان، Notion، Google Docs یا مرورگری کپی می‌کنید که گیومه‌های ASCII را خودکار با گیومه‌های تایپوگرافیک عوض می‌کند، پیدا می‌شوند. پارسرهای JSON فقط " ساده ASCII را می‌پذیرند.
گاهی تنظیمات خراب به شکل «JSON parse error» دیده نمی‌شود، بلکه به شکل 429 ظاهر می‌شود: کلاینت نبود پاسخ را محدودیت نرخ فرض می‌کند. راه‌حل همان است:
- هر
“”را با دست به"تبدیل کنید. - تنظیمات را مستقیم از همین مستندات کپی کنید — گیومه‌ها اینجا از قبل درست‌اند.
- با
cat -v config.jsonیاjq . config.jsonبررسی کنید — هر دو بایت خراب را نشان می‌دهند.
# Quick check: jq fails on the first smart quote
jq . ~/.claude/settings.json
# Auto-replace smart quotes with straight quotes
sed -i.bak $'s/[\u201c\u201d]/"/g' ~/.claude/settings.jsonجدول نشانه‌ها
| نشانه | علت محتمل | راه‌حل |
|---|---|---|
| 401 authentication_error در هر درخواست | کلید تنظیم نشده، قالبش نادرست است یا از کپی‌وپیست یک خط جدید / گیومهٔ اضافه به آن چسبیده است. | echo "${ANTHROPIC_API_KEY:?missing}" | wc -c # expect 68 (sk- + 64 hex + newline) |
| 429 'Insufficient balance on this API key' | موجودی کلید تمام شده است. تلاش دوباره کمکی نمی‌کند: پاسخ x-should-retry: false دارد. | curl -sH "Authorization: Bearer $ANTHROPIC_API_KEY" https://api.oneprovider.dev/v1/dashboard/balance # then top up your cabinet (bot or app.oneprovider.dev) |
| 403 permission_error 'API key expired' | کلید از تاریخ انقضای خود گذشته است. | کلید را تمدید کنید یا در حساب کاربری (صفحهٔ «کلیدها») کلید جدید صادر کنید. |
| 404 'The requested API endpoint does not exist' | base URL نادرست است: /v1 جا افتاده یا دوبار آمده است (/v1/v1). | کلاینت‌های OpenAI: https://api.oneprovider.dev/v1. Claude Code و SDKهای Anthropic: https://api.oneprovider.dev (بدون /v1). |
| 429 rate_limit_error در اوج درخواست‌ها | درخواست‌های زیاد در زمان کوتاه. | به Retry-After احترام بگذارید و با وقفهٔ فزاینده دوباره تلاش کنید. درخواست‌های موازی را کم کنید. |
| 400 'Model X is not available on this API key' | بستهٔ کلید شما این مدل را شامل نمی‌شود، یا نام مدل قدیمی است. | مدلی از GET /v1/models یا جدول در /docs/api/models انتخاب کنید. |
| 503 'Temporary provider issue on our side, retry in a minute' | یک خرابی موقت از سمت ما. کلید و درخواست شما سالم است. | با وقفهٔ فزاینده دوباره تلاش کنید: 1 ثانیه، 2 ثانیه، 4 ثانیه، تا یک دقیقه. |
| 504 'Service timed out; retry later' در یک فراخوانی بدون استریم | یک تولید طولانی (زمینهٔ بزرگ + ابزارها) ظرف 6 دقیقه شروع به پاسخ نکرد، یا از 10 دقیقه گذشت. | stream:true بدهید: استریم بلافاصله شروع به پاسخ می‌کند. اگر یک پاسخ بیش از 10 دقیقه لازم دارد، کار را تقسیم کنید. |
| فراخوانی ابزار با متن جایگزین شد («I would have called X...») | کلاینت tool_choice:{any|tool} فرستاد ← API آن را به auto + راهنما بازنویسی کرد؛ مدل راهنما را نپذیرفت. | پرامپت کاربر را دقیق‌تر کنید («Use the X tool to do Y»)، یا به مدل قوی‌تری بروید. |
| OPENAI_API_KEY کلید OneProvider مرا بازنویسی می‌کند | یک export قدیمی در shell rc شما (~/.zshrc، ~/.bashrc) مقدار جدید را می‌پوشاند. | در همین shell دستور unset OPENAI_API_KEY را اجرا کنید، سپس grep -nE 'OPENAI_API_KEY' ~/.zshrc را بزنید و آن را پاک کنید. |
| Codex می‌خواهد با ChatGPT وارد شوید یا می‌گوید «You've hit your usage limit» | ارائه‌دهندهٔ oneprovider فعال نیست: درخواست به ChatGPT رفته، نه به ما. | model_provider = "oneprovider" در همان بالای ~/.codex/config.toml (بالاتر از هر [table])، کلید در ONEPROVIDER_API_KEY، و یک وظیفهٔ محلی تازه. به /docs/clients/codex نگاه کنید. |
| Cursor / Claude Code: پاسخ استریم وسط توکن قطع می‌شود | تقریباً همیشه یک پروکسی شبکه یا VPN سمت کلاینت تکه‌های SSE را بافر می‌کند. | پروکسی/VPN را خاموش کنید و دوباره امتحان کنید. ما تکه‌ها را به محض آماده شدن می‌فرستیم، بدون بافر. |
دستورهای یک‌خطی تشخیصی
اگر جدول نشانه‌ها مورد شما را پوشش نداد، این سه مدرک را جمع کنید:
bash# 1. Confirm reach + auth
curl -sS -o /dev/null -w "HTTP %{http_code} total %{time_total}s\n" \
https://api.oneprovider.dev/v1/models -H "x-api-key: $ANTHROPIC_API_KEY"
# 2. Reproduce the failing call with -v (verbose headers)
curl -sv https://api.oneprovider.dev/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{"model":"claude-sonnet-5-5","max_tokens":32,"messages":[{"role":"user","content":"hi"}]}'
# 3. Check your current balance (also shown in the cabinet: the @oneprovider_robot bot or app.oneprovider.dev)
curl -s https://api.oneprovider.dev/v1/dashboard/balance \
-H "Authorization: Bearer $ANTHROPIC_API_KEY"چه زمانی ارجاع دهیم
سه خروجی بالا + 8 نویسهٔ اول کلید + یک زمان UTC را برای @Oneproviderhelpbot بفرستید. همین برای ما کافی است که ظرف چند دقیقه درخواست شما را در لاگ‌ها پیدا کنیم. دربارهٔ آنچه نیازی به آن نداریم (و هرگز نمی‌خواهیم) به دریافت پشتیبانی نگاه کنید.
آخرین به‌روزرسانی: 2026-11-08 باگی پیدا کردید؟ @Oneproviderhelpbot