حل مشكلات مفتاح 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 (HTTP status code)، مع رسالة قصيرة.

الرقم يخبرك بنوع المشكلة، والرسالة تعطي التفاصيل. ويحوّل Oriveo الأخطاء الشائعة إلى عناوين واضحة مثل «مفتاح API غير صالح» أو «تم استهلاك حصة المزود»، وشرحها في الأسفل.

دليل سريع: 401 و402 و403 و429 و5xx

نقطة البداية هنا: إيجاد رقم الخطأ، ثم قراءة القسم المقابل أدناه. ويتبع هذا الملخص صفحات الأخطاء لدى OpenAI وAnthropic ومزوّدين آخرين حتى 18 نوفمبر 2026.

دليل سريع: 401 و402 و403 و429 و5xx
الكودمعناه عادةًهل يفيد الانتظار؟الحل
401المفتاح خاطئ: حرف ناقص، أو مسافة زائدة، أو مفتاح محذوف، أو مفتاح من مزوّد آخر أو إقليم آخرلانسخ المفتاح من جديد أو إنشاء مفتاح جديد؛ والتحقق من المزوّد والإقليم
402الدفع مطلوب: نفد الرصيد المدفوع مسبقًا، أو توجد مشكلة في الفوترةلاشحن الرصيد، أو إصلاح وسيلة الدفع في صفحة الفوترة لدى المزوّد
403المفتاح يعمل لكنه غير مسموح له: بلد أو منطقة غير مدعومة، أو لا وصول إلى ذلك النموذج، أو خطوة تحقق مطلوبةلامراجعة المناطق المدعومة، وصلاحيات المفتاح، وأي تحقق مطلوب
404اسم النموذج أو العنوان خاطئلااختيار نموذج آخر أو مراجعة العنوان
429طلبات كثيرة في وقت قصير، أو لدى بعض المزوّدين رصيد فارغ أو حد إنفاقغالبًا، إن كان حد معدلالانتظار ثم إعادة المحاولة؛ وإن ذكرت الرسالة quota أو balance أو credit أو spend limit، فالحل شحن الرصيد أو رفع الحد
500–504، 529عطل أو ضغط زائد من جهة المزوّدعادةًالمحاولة لاحقًا أو تبديل النموذج

لماذا تظهر رسالة «رصيد غير كافٍ» أو «تجاوز الحصة»؟

معظم المزوّدين يشترطون رصيدًا مدفوعًا مسبقًا أو وسيلة فوترة فعّالة قبل أن يعمل الـ API، ولكلٍّ منهم طريقته في الإبلاغ عن نفاد الرصيد. والمفتاح الجديد لا يحل أيًّا من هذه الحالات؛ فالحل إضافة رصيد.

هذا هو الكود الذي يوثّقه كل واحد من المزوّدين الـ 15 المدمجين في Oriveo عند نفاد رصيدك. وعبارة «غير مذكور» تعني أن وثائق المزوّد، كما رُوجعت في 18 نوفمبر 2026، لا تحدد كود HTTP لهذه الحالة.

لماذا تظهر رسالة «رصيد غير كافٍ» أو «تجاوز الحصة»؟
المزوّدالكود عند نفاد الرصيدنص الرسالةالصفحة الرسمية
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_errorplatform.claude.com/docs/en/api/errors (الأكواد)؛ platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (الرسالة)
Google Gemini402 (الفوترة المدفوعة مسبقًا)payment_required؛ وقد يعني 403 أيضًا رصيدًا غير مسدد في Cloud Billingaistudio.google.com/docs/api-errors
OpenRouter402لا يكفي رصيد حسابك أو رصيد مفتاح API (insufficient credits)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 يُختار الإقليم المطابق من محدد «الـ Endpoint الرسمي» على الويب («نقطة النهاية الرسمية» على Android، و«عنوان الطلب الرسمي» على iPhone).
  • إذا حُذف المفتاح أو أُلغي أو انتهت صلاحيته، فالحل إنشاء مفتاح جديد.

402: الدفع مطلوب أو الرصيد غير كافٍ

يتعلق 402 بالمال: الرصيد المدفوع مسبقًا فارغ، أو وسيلة الدفع فشلت. الحل شحن الرصيد أو تحديث بيانات الدفع في صفحة الفوترة لدى المزوّد، ثم إعادة الإرسال. والانتظار لا يفيد.

في Oriveo يظهر هذا الخطأ بعنوان «تم استهلاك حصة المزود»، مع الرسالة: «يفيد المزود بأن حصة أو رصيد مفتاح API هذا قد نفد. تحقق من الفوترة لدى المزود أو بدّل النموذج.»

403: الطلب ممنوع أو الصلاحية مرفوضة

يعني 403 أن المزوّد تعرّف على المفتاح لكنه لا يسمح بالطلب. ويختلف السبب من مزوّد لآخر:

  • تعيد OpenAI الرسالة «Country, region, or territory not supported» عند استخدام الـ API من بلد لا تدعمه. وكل مزوّد ينشر قائمة البلدان المدعومة لديه.
  • تعيد Gemini الخطأ 403 حين يحتاج مشروع في الباقة المجانية إلى تحقق (FREE_TIER_VERIFICATION_REQUIRED)، أو حين يكون على حساب Cloud Billing المرتبط رصيد غير مسدد، أو حين تحظر Google مفتاحًا أُبلغ عن تسرّبه.
  • تعيد Anthropic الخطأ permission_error حين لا يستطيع المفتاح استخدام المورد المطلوب؛ والحل مراجعة إعدادات المؤسسة (organisation) ومساحة العمل (workspace).
  • يعيد OpenRouter الخطأ 403 حين يُحظر الطلب بسبب الصلاحيات أو الإشراف على المحتوى أو ضوابط الحماية أو حد الميزانية.
  • تشترط SiliconFlow التحقق من الهوية لبعض النماذج.
  • تستخدم Qwen الخطأ 403 للحساب الذي عليه متأخرات، وكذلك AllocationQuota.FreeTierOnly حين تُستهلك الحصة المجانية ويكون إعداد «Free Quota Only» مفعّلًا.

429: طلبات كثيرة، أو حد المعدل، أو تجاوز الحصة

في أغلب الحالات يعني 429 إرسال طلبات أو رموز (tokens) كثيرة في وقت قصير. هذا هو حد المعدل (rate limit)، ويزول بالانتظار بضع عشرات من الثواني. وإن تضمّن الرد مهلة Retry-After، فالانتظار يكون بقدرها.

ويستخدم عدد من المزوّدين الكود 429 أيضًا للرصيد الفارغ أو لحد الإنفاق، وهنا لا يفيد الانتظار: OpenAI (credit_balance_exhausted، أو حد إنفاق مضبوط في حسابك)، وKimi (exceeded_current_quota_error)، وZ.ai (الكود 1113)، وAnthropic حين تبلغ المؤسسة حد إنفاقها الشهري (enforced_spend_limit_reached)، ويستمر ذلك حتى الشهر التالي ما لم يُطلب مستوى أعلى.

والباقات المجانية أضيق. فالباقة المجانية في Gemini والنماذج المجانية في OpenRouter لها حدود في الدقيقة وفي اليوم.

في Oriveo يظهر حد المعدل بعنوان «تجاوز الحد المسموح» على الويب أو «تم تقييد معدل المزود» على iPhone وAndroid. وإن ذكرت الرسالة الحصة أو الرصيد، يعرض Oriveo بدلًا منه «تم استهلاك حصة المزود».

ماذا تعني رسائل الخطأ في Oriveo؟

هذه هي الرسائل التي قد تظهر في Oriveo، بصيغتها العربية في التطبيق:

ماذا تعني رسائل الخطأ في Oriveo؟
ما يعرضه Oriveoالمعنىالحل
تم الحفظ، لكن المفتاح يبدو غير صالح. يمكنك التحقق منه لاحقًا في إعدادات المزوّد.حفظ Oriveo المزوّد، لكن المزوّد رفض المفتاح أثناء التحققنسخ المفتاح من جديد وتحديثه في إعدادات ذلك المزوّد
مفتاح API غير صالحأعاد المزوّد 401 أو 403مراجعة المفتاح أو استبداله؛ ومع 403، مراجعة الإقليم والصلاحيات
تم استهلاك حصة المزوديفيد المزوّد بأن رصيد هذا المفتاح أو حصته نفدت (402، أو 429 مع ذكر الحصة)شحن الرصيد لدى المزوّد، أو التبديل إلى نموذج آخر
تجاوز الحد المسموح (الويب) / تم تقييد معدل المزود (iPhone وAndroid)طلبات كثيرة في الوقت الحالي (429)الانتظار قليلًا ثم إعادة المحاولة
تم استهلاك الحصة المجانية (الويب وiPhone) / تم بلوغ حصة Free (Android)نفدت حصة Oriveo Free لهذا اليوم؛ ولا علاقة لذلك بمفتاحك الخاصإضافة مفتاح API الخاص بك، أو انتظار إعادة التعيين عند 00:00 UTC
شاشة «مزودو الخدمة» في Oriveo تعرض مزوّدين متصلين مثل OpenAI وZ.ai وGroq وGemini وAnthropic، مع إنفاق كل منهم
فتح أي مزوّد من هذه القائمة لمراجعة مفتاحه أو استبداله.

هل تستخدم نقطة نهاية مخصصة أو مُرحِّلًا (relay) أو بوابة (gateway)؟

عند الاتصال عبر نقطة نهاية مخصصة، قد يأتي الخطأ من تلك الخدمة أو من المزوّد الذي يقف خلفها. فحين يعرض Oriveo الرسالة «تعذّر على هذا الاتصال الوصول إلى مزوّده المصدر»، فقد يكون حساب الخدمة نفسها لدى المزوّد غير صالح أو نفد رصيده أو بلغ حد المعدل. وهذا ليس خطأ في إعداداتك؛ والحل التبديل إلى اتصال آخر أو التواصل مع الجهة المشغّلة للخدمة.

قائمة تحقق قبل إنشاء مفتاح جديد

المفتاح الجديد يحل الخطأ 401 ولا يكاد يحل غيره. لذلك تُراجَع هذه القائمة أولًا:

  • اختيار المزوّد الصحيح، والإقليم الصحيح مع Kimi وMiniMax وQwen وSiliconFlow وZ.ai.
  • نسخ المفتاح كاملًا، دون مسافات.
  • وجود رصيد في الحساب، أو وسيلة فوترة فعّالة.
  • وجود بلدك أو منطقتك في قائمة المناطق التي يدعمها المزوّد.
  • إتاحة النموذج المختار لحسابك أو لمستواك.

أسئلة شائعة حول التطبيق

لماذا لا يعمل مفتاح 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، فالحل إضافة رصيد لا الانتظار.
لماذا يظهر insufficient_quota مع مفتاح OpenAI API؟
لأن حساب OpenAI API لم يبقَ فيه رصيد مدفوع مسبقًا. تعيد OpenAI الخطأ 429 بالكود credit_balance_exhausted، وقد يبقى نوع الخطأ insufficient_quota. الحل إضافة رصيد من إعدادات الفوترة في OpenAI؛ فالمفتاح الجديد لا يفيد.
لماذا لا يعمل مفتاح API الجديد رغم نسخه بشكل صحيح؟
السبب عادةً أن الحساب ليس فيه رصيد بعد أو أن الفوترة غير مضبوطة، أو أن المفتاح تابع لإقليم آخر، أو أن الـ API غير متاح في بلدك. والأفضل مراجعة هذه النقاط قبل إنشاء مفتاح آخر.

قراءات ذات صلة

من المدوّنة

سبب واضح لكل خطأ في مفاتيحك

يكفي فتح تطبيق الويب أو تنزيل Oriveo على iPhone أو Android وإضافة مفاتيح من 15 مزوّدًا، ليظهر سبب واضح كلما فشل طلب.

ليس لديك مفتاح API بعد؟ ابدأ باستخدام Oriveo Free.