عیب‌یابی کلید API

کلید 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 بررسی شده‌اند.
Oriveo روی iPhone: صفحه ارائه‌دهندگان که ارائه‌دهندگان متصل‌شده و هزینه این ماه را فهرست می‌کند.

«کلید API کار نمی‌کند» دقیقاً یعنی چه؟

کلید API رمزی محرمانه است که برنامه همراه هر درخواست می‌فرستد تا ارائه‌دهنده‌ی هوش مصنوعی بداند شما هستید و هزینه را از کدام حساب بردارد. وقتی مشکلی پیش بیاید، ارائه‌دهنده با یک خطا پاسخ می‌دهد: یک عدد سه‌رقمی به نام کد وضعیت HTTP، همراه با یک پیام کوتاه.

عدد نوع مشکل را نشان می‌دهد و پیام جزئیاتش را. Oriveo خطاهای رایج را به عنوان‌های ساده‌ای مثل «کلید API نامعتبر» یا «سهمیه ارائه‌دهنده تمام شد» تبدیل می‌کند که پایین‌تر در همین صفحه توضیح داده شده‌اند.

راهنمای سریع: 401، 402، 403، 429 و 5xx

از اینجا شروع کنید. عدد خطایتان را پیدا کنید و بعد بخش مربوط به آن را در ادامه بخوانید. این خلاصه بر پایه‌ی صفحه‌های خطای OpenAI، Anthropic و ارائه‌دهندگان دیگر تا 18 نوامبر 2026 است.

راهنمای سریع: 401، 402، 403، 429 و 5xx
کدمعمولاً یعنیبا صبر کردن درست می‌شود؟چه کنید
401کلید اشتباه است: نویسه‌ای جا افتاده، فاصله‌ی اضافه دارد، کلید حذف شده، یا کلید متعلق به ارائه‌دهنده یا منطقه‌ی دیگری استنهکلید را دوباره کپی کنید یا کلید تازه بسازید؛ ارائه‌دهنده و منطقه را بررسی کنید
402پرداخت لازم است: موجودی یا اعتبار پیش‌پرداخت تمام شده، یا مشکلی در صورت‌حساب هستنهموجودی را شارژ کنید یا روش پرداخت را در صفحه‌ی صورت‌حساب ارائه‌دهنده درست کنید
403کلید کار می‌کند اما مجاز نیست: کشور یا منطقه پشتیبانی نمی‌شود، به آن مدل دسترسی ندارید، یا یک مرحله‌ی تأیید باقی مانده استنهمنطقه‌های پشتیبانی‌شده، مجوزهای کلید و مرحله‌های تأیید را بررسی کنید
404نام مدل یا نشانی اشتباه استنهمدل دیگری انتخاب کنید یا نشانی را بررسی کنید
429درخواست‌های زیاد در زمان کوتاه، یا نزد بعضی ارائه‌دهندگان، موجودی صفر یا سقف هزینهاغلب، اگر محدودیت نرخ باشدصبر کنید و دوباره امتحان کنید؛ اگر پیام از quota، balance، credit یا سقف هزینه حرف می‌زند، موجودی را شارژ کنید یا سقف را بالا ببرید
500–504، 529خرابی یا شلوغی در سمت ارائه‌دهندهمعمولاًبعداً دوباره امتحان کنید یا مدل را عوض کنید

چرا خطای کمبود موجودی یا سهمیه (insufficient balance / quota) می‌گیرم؟

بیشتر ارائه‌دهندگان پیش از اینکه API کار کند، اعتبار پیش‌پرداخت یا یک روش پرداخت فعال می‌خواهند و هرکدام تمام‌شدن موجودی را به شیوه‌ی خودش اعلام می‌کند. کلید تازه هیچ‌کدام از این‌ها را درست نمی‌کند؛ افزودن اعتبار درست می‌کند.

این کدی است که هر یک از 15 ارائه‌دهنده‌ی داخلی Oriveo برای تمام‌شدن موجودی یا اعتبار در مستنداتش آورده است. «اعلام نشده» یعنی مستندات آن ارائه‌دهنده، که در 18 نوامبر 2026 بررسی شد، برای این حالت کد HTTP مشخصی نیاورده است.

چرا خطای کمبود موجودی یا سهمیه (insufficient balance / quota) می‌گیرم؟
ارائه‌دهندهکد هنگام تمام‌شدن موجودیمتن پیامصفحه‌ی رسمی
OpenAI429credit_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 Gemini402 (صورت‌حساب پیش‌پرداخت)payment_required؛ 403 هم می‌تواند به معنای بدهی پرداخت‌نشده در Cloud Billing باشدaistudio.google.com/docs/api-errors
OpenRouter402Your account or API key has insufficient credits (اعتبار حساب یا کلید API شما کافی نیست)openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)اعلام نشدهوقتی اعتبار پیش‌پرداخت تمام شود، درخواست‌ها رد می‌شوندdocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
Groqدر مستندات نیامدهGroq پس از مصرف صورت‌حساب می‌دهد؛ صفحه‌ی خطاهایش هیچ خطای موجودی‌ای نداردconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxاعلام نشده (کد تجاری 1008)insufficient balanceplatform.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)403Arrearage یا isv.OUT_OF_SERVICE (حساب بدهکار است)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.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 نشان می‌دهدمعنیچه کنید
ذخیره شد، اما کلید نامعتبر به نظر می‌رسد. می‌توانید بعداً آن را در تنظیمات ارائه‌دهنده بررسی کنید.Oriveo ارائه‌دهنده را ذخیره کرده، اما ارائه‌دهنده هنگام بررسی، کلید را رد کرده استکلید را دوباره کپی کنید و در تنظیمات همان ارائه‌دهنده به‌روز کنید
کلید API نامعتبرارائه‌دهنده 401 یا 403 برگردانده استکلید را بررسی یا عوض کنید؛ برای 403، منطقه و مجوزها را بررسی کنید
سهمیه ارائه‌دهنده تمام شدارائه‌دهنده می‌گوید اعتبار یا سهمیه‌ی این کلید تمام شده است (402، یا 429 همراه با اشاره به سهمیه)نزد ارائه‌دهنده موجودی را شارژ کنید یا به مدل دیگری بروید
محدودیت نرخ درخواست (وب) / ارائه‌دهنده محدودیت نرخ اعمال کرده است (iPhone و Android)فعلاً درخواست‌ها بیش از حد است (429)کمی صبر کنید و دوباره امتحان کنید
سهمیه رایگان تمام شدسهمیه‌ی امروز Oriveo Free تمام شده است؛ ربطی به کلید خودتان نداردکلید API خودتان را اضافه کنید یا تا تازه شدن سهمیه در ساعت 00:00 UTC صبر کنید
صفحه‌ی «ارائه‌دهندگان» در Oriveo با فهرست ارائه‌دهندگان متصل مثل OpenAI، Z.ai، Groq، Gemini و Anthropic و هزینه‌ی هرکدام
برای بررسی یا عوض کردن کلید یک ارائه‌دهنده، آن را از همین فهرست باز کنید.

از نقطه‌ی اتصال سفارشی، سرویس واسط یا gateway استفاده می‌کنید؟

اگر از طریق یک نقطه‌ی اتصال سفارشی وصل می‌شوید، خطا ممکن است از خود آن سرویس باشد یا از ارائه‌دهنده‌ای که پشت آن است. وقتی Oriveo می‌گوید «این اتصال نتوانست به ارائه‌دهنده بالادست خود برسد»، ممکن است حساب خود آن سرویس نزد ارائه‌دهنده نامعتبر باشد، اعتبارش تمام شده باشد یا با محدودیت نرخ روبه‌رو شده باشد. این مشکل از تنظیمات شما نیست؛ به اتصال دیگری بروید یا با گرداننده‌ی آن سرویس تماس بگیرید.

پیش از ساختن کلید تازه این‌ها را بررسی کنید

کلید تازه فقط خطای 401 را درست می‌کند و تقریباً هیچ چیز دیگری را. اول این فهرست را مرور کنید:

  • ارائه‌دهنده‌ی درست را انتخاب کرده‌اید و برای Kimi، MiniMax، Qwen، SiliconFlow و Z.ai، منطقه‌ی درست را.
  • همه‌ی کلید را بدون فاصله کپی کرده‌اید.
  • حساب اعتبار دارد یا یک روش پرداخت فعال دارد.
  • کشور یا منطقه‌ی شما در فهرست پشتیبانی‌شده‌ی ارائه‌دهنده هست.
  • مدلی که انتخاب کرده‌اید برای حساب یا سطح (tier) شما در دسترس است.

پرسش‌های متداول

چرا کلید API من کار نمی‌کند؟
به شماره‌ی خطا نگاه کنید. 401 یعنی کلید اشتباه است، 402 یعنی موجودی یا اعتبارتان تمام شده، 403 یعنی درخواست مجاز نیست (اغلب به‌خاطر منطقه یا مجوزها) و 429 یعنی درخواست‌ها بیش از حد بوده یا، نزد بعضی ارائه‌دهندگان، موجودی صفر شده است.
خطای 401 برای کلید API یعنی چه؟
ارائه‌دهنده کلید را نمی‌شناسد. آن را بدون فاصله دوباره کپی کنید، بررسی کنید که متعلق به همان ارائه‌دهنده و منطقه‌ای باشد که انتخاب کرده‌اید، یا کلید تازه بسازید.
خطای 402 Payment Required چیست؟
موجودی یا اعتبار پیش‌پرداخت شما تمام شده یا مشکلی در پرداخت هست. DeepSeek، OpenRouter، Mistral، Together، Fireworks و صورت‌حساب پیش‌پرداخت Gemini از این کد استفاده می‌کنند. در صفحه‌ی صورت‌حساب ارائه‌دهنده موجودی را شارژ کنید؛ صبر کردن مشکل را حل نمی‌کند.
خطای 429 محدودیت نرخ است یا مشکل سهمیه؟
می‌تواند هر دو باشد. معمولاً محدودیت نرخ است که با کمی صبر برطرف می‌شود. اما OpenAI، Kimi و Z.ai وقتی موجودی صفر باشد هم 429 برمی‌گردانند؛ پس اگر پیام از quota، balance یا credit حرف می‌زند، به‌جای صبر کردن اعتبار اضافه کنید.
چرا کلید OpenAI من خطای insufficient_quota می‌دهد؟
حساب API شما در OpenAI دیگر اعتبار پیش‌پرداخت ندارد. OpenAI در این حالت 429 با کد credit_balance_exhausted برمی‌گرداند و نوع خطا ممکن است هنوز insufficient_quota باشد. در تنظیمات صورت‌حساب OpenAI اعتبار اضافه کنید؛ کلید تازه کمکی نمی‌کند.
چرا کلید API تازه‌ام با اینکه درست کپی‌اش کرده‌ام کار نمی‌کند؟
معمولاً چون حساب هنوز اعتبار ندارد یا صورت‌حساب تنظیم نشده، کلید متعلق به منطقه‌ی دیگری است، یا API در کشور شما ارائه نمی‌شود. پیش از ساختن کلید دیگر، این‌ها را بررسی کنید.

مطالب مرتبط

برای هر کلید، دلیل خطا را به زبان ساده ببینید

برنامه‌ی وب را باز کنید یا Oriveo را برای iPhone یا Android دانلود کنید، کلیدهای 15 ارائه‌دهنده را اضافه کنید و وقتی درخواستی ناموفق شد، دلیلش را روشن ببینید.

هنوز کلید API ندارید؟ با Oriveo Free بدون آن شروع کنید.