کلید API کار نمیکند؟ رفع خطاهای 401، 402، 403 و 429
چرا کلید API هوش مصنوعی از کار میافتد: معنای 401، 402، 403 و 429، کدی که هر ارائهدهنده برای تمامشدن موجودی میفرستد و راه رفع هرکدام.
- وقتی کلید API هوش مصنوعی «کار نمیکند»، شمارهی خطا دلیلش را میگوید: 401 یعنی خود کلید اشتباه است، 402 معمولاً یعنی موجودی یا اعتبارتان تمام شده، 403 یعنی کلید اجازهی آن کار را ندارد و 429 یعنی درخواستها بیش از حد بوده یا، نزد بعضی ارائهدهندگان، موجودی صفر شده است.
- ارائهدهندگان برای تمامشدن موجودی کد یکسانی ندارند. DeepSeek، OpenRouter، Mistral، Together، Fireworks و صورتحساب پیشپرداخت Gemini از 402 استفاده میکنند؛ OpenAI، Kimi و Z.ai از 429؛ و Qwen در Alibaba Cloud از 403. متن پیام را بخوانید، نه فقط شماره را.
- خطاهای موجودی با صبر کردن برطرف نمیشوند، اما محدودیت نرخ درخواست معمولاً برطرف میشود. جدول پایین صفحهی رسمی خطاهای هر ارائهدهنده را آورده است؛ همه در 18 نوامبر 2026 بررسی شدهاند.

«کلید API کار نمیکند» دقیقاً یعنی چه؟
کلید API رمزی محرمانه است که برنامه همراه هر درخواست میفرستد تا ارائهدهندهی هوش مصنوعی بداند شما هستید و هزینه را از کدام حساب بردارد. وقتی مشکلی پیش بیاید، ارائهدهنده با یک خطا پاسخ میدهد: یک عدد سهرقمی به نام کد وضعیت HTTP، همراه با یک پیام کوتاه.
عدد نوع مشکل را نشان میدهد و پیام جزئیاتش را. Oriveo خطاهای رایج را به عنوانهای سادهای مثل «کلید API نامعتبر» یا «سهمیه ارائهدهنده تمام شد» تبدیل میکند که پایینتر در همین صفحه توضیح داده شدهاند.
راهنمای سریع: 401، 402، 403، 429 و 5xx
از اینجا شروع کنید. عدد خطایتان را پیدا کنید و بعد بخش مربوط به آن را در ادامه بخوانید. این خلاصه بر پایهی صفحههای خطای OpenAI، Anthropic و ارائهدهندگان دیگر تا 18 نوامبر 2026 است.
| کد | معمولاً یعنی | با صبر کردن درست میشود؟ | چه کنید |
|---|---|---|---|
| 401 | کلید اشتباه است: نویسهای جا افتاده، فاصلهی اضافه دارد، کلید حذف شده، یا کلید متعلق به ارائهدهنده یا منطقهی دیگری است | نه | کلید را دوباره کپی کنید یا کلید تازه بسازید؛ ارائهدهنده و منطقه را بررسی کنید |
| 402 | پرداخت لازم است: موجودی یا اعتبار پیشپرداخت تمام شده، یا مشکلی در صورتحساب هست | نه | موجودی را شارژ کنید یا روش پرداخت را در صفحهی صورتحساب ارائهدهنده درست کنید |
| 403 | کلید کار میکند اما مجاز نیست: کشور یا منطقه پشتیبانی نمیشود، به آن مدل دسترسی ندارید، یا یک مرحلهی تأیید باقی مانده است | نه | منطقههای پشتیبانیشده، مجوزهای کلید و مرحلههای تأیید را بررسی کنید |
| 404 | نام مدل یا نشانی اشتباه است | نه | مدل دیگری انتخاب کنید یا نشانی را بررسی کنید |
| 429 | درخواستهای زیاد در زمان کوتاه، یا نزد بعضی ارائهدهندگان، موجودی صفر یا سقف هزینه | اغلب، اگر محدودیت نرخ باشد | صبر کنید و دوباره امتحان کنید؛ اگر پیام از quota، balance، credit یا سقف هزینه حرف میزند، موجودی را شارژ کنید یا سقف را بالا ببرید |
| 500–504، 529 | خرابی یا شلوغی در سمت ارائهدهنده | معمولاً | بعداً دوباره امتحان کنید یا مدل را عوض کنید |
چرا خطای کمبود موجودی یا سهمیه (insufficient balance / quota) میگیرم؟
بیشتر ارائهدهندگان پیش از اینکه API کار کند، اعتبار پیشپرداخت یا یک روش پرداخت فعال میخواهند و هرکدام تمامشدن موجودی را به شیوهی خودش اعلام میکند. کلید تازه هیچکدام از اینها را درست نمیکند؛ افزودن اعتبار درست میکند.
این کدی است که هر یک از 15 ارائهدهندهی داخلی Oriveo برای تمامشدن موجودی یا اعتبار در مستنداتش آورده است. «اعلام نشده» یعنی مستندات آن ارائهدهنده، که در 18 نوامبر 2026 بررسی شد، برای این حالت کد HTTP مشخصی نیاورده است.
| ارائهدهنده | کد هنگام تمامشدن موجودی | متن پیام | صفحهی رسمی |
|---|---|---|---|
| OpenAI | 429 | credit_balance_exhausted (نوع خطا ممکن است هنوز insufficient_quota باشد) | developers.openai.com/api/docs/guides/error-codes |
| Anthropic (Claude) | اعلام نشده | «Your credit balance is too low to access the Anthropic API»؛ مشکلات پرداخت 402 billing_error برمیگردانند | platform.claude.com/docs/en/api/errors (کدها)؛ platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (پیام) |
| Google Gemini | 402 (صورتحساب پیشپرداخت) | payment_required؛ 403 هم میتواند به معنای بدهی پرداختنشده در Cloud Billing باشد | aistudio.google.com/docs/api-errors |
| OpenRouter | 402 | Your account or API key has insufficient credits (اعتبار حساب یا کلید API شما کافی نیست) | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | اعلام نشده | وقتی اعتبار پیشپرداخت تمام شود، درخواستها رد میشوند | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | در مستندات نیامده | Groq پس از مصرف صورتحساب میدهد؛ صفحهی خطاهایش هیچ خطای موجودیای ندارد | console.groq.com/docs/errors |
| Together AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | اعلام نشده (کد تجاری 1008) | insufficient balance | platform.minimax.io/docs/api-reference/errorcode |
| Z.ai (GLM) | 429 (کد 1113) | Insufficient balance or no resource package. Please recharge. | docs.z.ai/api-reference/api-code |
| Qwen (Alibaba Cloud) | 403 | Arrearage یا isv.OUT_OF_SERVICE (حساب بدهکار است) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | در مستندات نیامده | هیچ خطای موجودیای فهرست نشده است | docs.siliconflow.com/en/faqs/error-code |
401: کلید API نامعتبر یا احراز هویت ناموفق
خطای 401 یعنی ارائهدهنده کلید را نمیشناسد. پیامهای رایج اینهاست: «Incorrect API key provided» (OpenAI)، «authentication_error» (Anthropic)، «Authentication Fails» (DeepSeek) و «Invalid API key: this is not an OpenRouter API key» (OpenRouter).
- کلید را دوباره از سایت ارائهدهنده کپی کنید و ببینید نویسهای جا نیفتاده باشد و در ابتدا یا انتهایش فاصله نباشد.
- مطمئن شوید کلید متعلق به همان ارائهدهندهای است که انتخاب کردهاید. کلید OpenAI بهجای کلید OpenRouter کار نمیکند و برعکس.
- Kimi، MiniMax و Qwen پلتفرمهای منطقهای جداگانه دارند و کلید یکی روی دیگری کار نمیکند. در Oriveo، منطقهی مطابق را در انتخابگر «نقطه پایانی رسمی» (در iPhone: «نشانی درخواست رسمی») انتخاب کنید.
- اگر کلید حذف شده، باطل شده یا منقضی شده است، کلید تازه بسازید.
402: پرداخت لازم است یا موجودی کافی نیست
خطای 402 به پول مربوط است: موجودی پیشپرداخت خالی است یا روش پرداخت ناموفق بوده است. در صفحهی صورتحساب ارائهدهنده موجودی را شارژ کنید یا اطلاعات پرداخت را بهروز کنید و دوباره بفرستید. صبر کردن کمکی نمیکند.
در Oriveo این خطا با عنوان «سهمیه ارائهدهنده تمام شد» و این توضیح نمایش داده میشود: «ارائهدهنده گزارش کرده است که سهمیه یا اعتبار این کلید API تمام شده است. صورتحساب خود را نزد ارائهدهنده بررسی کنید یا مدل را تغییر دهید.»
403: دسترسی ممنوع یا مجوز رد شده
خطای 403 یعنی ارائهدهنده کلید را شناخته، اما اجازهی آن درخواست را نمیدهد. دلیلش به ارائهدهنده بستگی دارد:
- وقتی از API در کشوری استفاده شود که OpenAI از آن پشتیبانی نمیکند، OpenAI پیام «Country, region, or territory not supported» را برمیگرداند. هر ارائهدهنده فهرست کشورهای پشتیبانیشدهاش را منتشر میکند.
- Gemini در این حالتها 403 برمیگرداند: وقتی پروژهای در سطح رایگان باید تأیید شود (FREE_TIER_VERIFICATION_REQUIRED)، وقتی حساب Cloud Billing متصل بدهی پرداختنشده دارد، یا وقتی Google کلیدی را که لو رفتنش گزارش شده مسدود کرده است.
- Anthropic وقتی کلید اجازهی استفاده از آن منبع را نداشته باشد، permission_error برمیگرداند؛ تنظیمات سازمان (organization) و فضای کاری (workspace) خود را بررسی کنید.
- OpenRouter وقتی درخواست بهدلیل مجوزها، نظارت بر محتوا، یک محافظ (guardrail) یا سقف بودجه مسدود شود، 403 برمیگرداند.
- SiliconFlow برای بعضی مدلها تأیید هویت میخواهد.
- Qwen برای حساب بدهکار از 403 استفاده میکند، و نیز برای AllocationQuota.FreeTierOnly، وقتی سهمیهی رایگان تمام شده و تنظیم «Free Quota Only» روشن است.
429: درخواستهای بیش از حد، محدودیت نرخ یا عبور از سهمیه
بیشتر وقتها 429 یعنی در زمان کوتاهی درخواست یا توکن بیش از حد فرستادهاید. این محدودیت نرخ است و اگر چند ده ثانیه صبر کنید برطرف میشود. اگر پاسخ زمان Retry-After دارد، همانقدر صبر کنید.
چند ارائهدهنده برای موجودی صفر یا سقف هزینه هم از 429 استفاده میکنند و در این حالتها صبر کردن فایده ندارد: OpenAI (credit_balance_exhausted، یا سقف هزینهای که خودتان گذاشتهاید)، Kimi (exceeded_current_quota_error)، Z.ai (کد 1113)، و Anthropic وقتی سازمان به سقف هزینهی ماهانهاش برسد (enforced_spend_limit_reached)؛ این حالت تا ماه بعد ادامه دارد، مگر اینکه سطح (tier) بالاتری درخواست کنید.
سطحهای رایگان محدودترند. سطح رایگان Gemini و مدلهای رایگان OpenRouter سقف دقیقهای و روزانه دارند.
در Oriveo، محدودیت نرخ در وب با «محدودیت نرخ درخواست» و در iPhone و Android با «ارائهدهنده محدودیت نرخ اعمال کرده است» نمایش داده میشود. اگر پیام از سهمیه یا اعتبار حرف بزند، Oriveo بهجای آن «سهمیه ارائهدهنده تمام شد» را نشان میدهد.
پیامهای خطای Oriveo یعنی چه؟
اینها پیامهایی است که ممکن است در Oriveo ببینید، با همان متنی که در نسخهی فارسی برنامه نمایش داده میشود:
| آنچه Oriveo نشان میدهد | معنی | چه کنید |
|---|---|---|
| ذخیره شد، اما کلید نامعتبر به نظر میرسد. میتوانید بعداً آن را در تنظیمات ارائهدهنده بررسی کنید. | Oriveo ارائهدهنده را ذخیره کرده، اما ارائهدهنده هنگام بررسی، کلید را رد کرده است | کلید را دوباره کپی کنید و در تنظیمات همان ارائهدهنده بهروز کنید |
| کلید API نامعتبر | ارائهدهنده 401 یا 403 برگردانده است | کلید را بررسی یا عوض کنید؛ برای 403، منطقه و مجوزها را بررسی کنید |
| سهمیه ارائهدهنده تمام شد | ارائهدهنده میگوید اعتبار یا سهمیهی این کلید تمام شده است (402، یا 429 همراه با اشاره به سهمیه) | نزد ارائهدهنده موجودی را شارژ کنید یا به مدل دیگری بروید |
| محدودیت نرخ درخواست (وب) / ارائهدهنده محدودیت نرخ اعمال کرده است (iPhone و Android) | فعلاً درخواستها بیش از حد است (429) | کمی صبر کنید و دوباره امتحان کنید |
| سهمیه رایگان تمام شد | سهمیهی امروز Oriveo Free تمام شده است؛ ربطی به کلید خودتان ندارد | کلید API خودتان را اضافه کنید یا تا تازه شدن سهمیه در ساعت 00:00 UTC صبر کنید |

از نقطهی اتصال سفارشی، سرویس واسط یا gateway استفاده میکنید؟
اگر از طریق یک نقطهی اتصال سفارشی وصل میشوید، خطا ممکن است از خود آن سرویس باشد یا از ارائهدهندهای که پشت آن است. وقتی Oriveo میگوید «این اتصال نتوانست به ارائهدهنده بالادست خود برسد»، ممکن است حساب خود آن سرویس نزد ارائهدهنده نامعتبر باشد، اعتبارش تمام شده باشد یا با محدودیت نرخ روبهرو شده باشد. این مشکل از تنظیمات شما نیست؛ به اتصال دیگری بروید یا با گردانندهی آن سرویس تماس بگیرید.
پیش از ساختن کلید تازه اینها را بررسی کنید
کلید تازه فقط خطای 401 را درست میکند و تقریباً هیچ چیز دیگری را. اول این فهرست را مرور کنید:
- ارائهدهندهی درست را انتخاب کردهاید و برای Kimi، MiniMax، Qwen، SiliconFlow و Z.ai، منطقهی درست را.
- همهی کلید را بدون فاصله کپی کردهاید.
- حساب اعتبار دارد یا یک روش پرداخت فعال دارد.
- کشور یا منطقهی شما در فهرست پشتیبانیشدهی ارائهدهنده هست.
- مدلی که انتخاب کردهاید برای حساب یا سطح (tier) شما در دسترس است.
پرسشهای متداول
چرا کلید API من کار نمیکند؟
خطای 401 برای کلید API یعنی چه؟
خطای 402 Payment Required چیست؟
خطای 429 محدودیت نرخ است یا مشکل سهمیه؟
چرا کلید OpenAI من خطای insufficient_quota میدهد؟
چرا کلید API تازهام با اینکه درست کپیاش کردهام کار نمیکند؟
مطالب مرتبط
برای هر کلید، دلیل خطا را به زبان ساده ببینید
برنامهی وب را باز کنید یا Oriveo را برای iPhone یا Android دانلود کنید، کلیدهای 15 ارائهدهنده را اضافه کنید و وقتی درخواستی ناموفق شد، دلیلش را روشن ببینید.
هنوز کلید API ندارید؟ با Oriveo Free بدون آن شروع کنید.