العودة إلى المدونة

استكشاف الأخطاءدليل

خطأ API 401 أو 404: مفتاح أو base URL أو معرّف نموذج خاطئ

اقرأ رمز الحالة، واعرف أي من ثلاثة أشياء خاطئ (المفتاح، base URL، معرّف النموذج) وأكّد الإصلاح بطلب curl واحد.

بواسطة CheapTokens Teamنُشر في 4 دقيقة قراءة

بطاقة خطأ بالحالة 401 مع تلميح لفحص المفتاح وbase URL ومعرّف النموذج
في هذه الصفحة
  1. الطريقة السريعة للتمييز بينهما
  2. 401: المفتاح لا يطابق نقطة النهاية
  3. 404 على كل النماذج: العنوان خاطئ
  4. 404 على نموذج واحد: معرّف النموذج
  5. أثبت الإصلاح بأمر curl واحد
  6. إذا لم يعمل بعد

فشل طلبك برمز حالة ولست متأكدًا مما يجب فحصه أولًا. الإجابة المختصرة: 401 عادةً يشير إلى المفتاح، و404 عادةً يعني أنك تطرق المكان الخطأ — إما العنوان (base URL والمسار) أو معرّف النموذج. ثلاثة أشياء يجب فحصها، بهذا الترتيب، وأمر curl واحد يثبت الإصلاح.

تسرد صفحة رموز الأخطاء لدى OpenAI (تم فحصها في 26 أكتوبر 2026) رسالتي 401: "Invalid Authentication" و"Incorrect API key provided". الإصلاح المذكور لكليهما واحد: افحص المفتاح أو أنشئ مفتاحًا جديدًا. لا توثّق الصفحة أي 404 لواجهة API نفسها، لذا بالنسبة لـ 404 تأتي القاعدة أدناه من كيفية عمل نقاط النهاية المتوافقة مع OpenAI، وليس من تلك الصفحة.

الطريقة السريعة للتمييز بينهما#

الحالة ما يقوله الخادم افحص أولًا
401 عادةً: لا أقبل هذا المفتاح المفتاح، وإلى أي مزوّد ينتمي
404 على كل النماذج عادةً: لا يوجد شيء على هذا العنوان base URL و/v1
404 على نموذج واحد فقط عادةً: العنوان سليم، لكن معرّف النموذج هذا غير معروف معرّف النموذج

تعتمد صياغة الرسالة على الخادم وعلى أداتك (Cline وAider وOpenCode وContinue كل منها يغلّف الأخطاء بطريقته)، لذا ابدأ من الرقم، ثم أكّد بفحص curl أدناه.

401: المفتاح لا يطابق نقطة النهاية#

القصة الكلاسيكية: نقلت أداة إلى مزوّد جديد، وغيّرت base URL، وتركت مفتاح المزوّد القديم في الإعدادات. العنوان جديد، والمفتاح قديم، فيجيب الخادم بـ 401. لا شيء معطّل؛ المفتاح فقط ينتمي إلى بيت مختلف.

ما يجب فحصه:

  1. أي مزوّد أصدر المفتاح؟ يجب أن يكون المزوّد الذي تستدعي عنوانه. مفتاح خدمة واحدة غير صالح على أخرى.
  2. أحرف دخيلة. مسافة أو فاصل سطر لُصق مع المفتاح، أو علامات اقتباس انتهت داخل القيمة.
  3. من أين تقرأه الأداة. متغير بيئة مضبوط في طرفية واحدة وليس في الطرفية التي بدأ منها محرّرك هو سبب متكرر. إذا كانت الأداة تحتوي على ملف إعدادات ومتغير بيئة معًا، فاعرف أيهما يفوز.
  4. مفتاح ملغى أو محذوف. المفتاح الذي حذفته أو ألغيته يتوقف عن العمل — أنشئ مفتاحًا جديدًا وضعه في الإعدادات.

إذا لم تكن متأكدًا من كيفية عمل المفاتيح أو أين تحفظها، ما هو مفتاح API وكيف تخزنه بأمان يغطي ذلك بكلمات بسيطة.

404 على كل النماذج: العنوان خاطئ#

base URL الخاص بـ CheapTokens هو https://api.cheaptokens.dev/v1. الأدوات وSDKs تضيف مسار نقطة النهاية بنفسها، لذا الأخطاء المعتادة تتعلق بـ /v1:

  • /v1 مفقود: تنتهي الأداة باستدعاء https://api.cheaptokens.dev/chat/completions.
  • /v1 مكرر: لصقت المسار الكامل في حقل يضيفه أصلًا، فتحصل على https://api.cheaptokens.dev/v1/v1/chat/completions.
  • النوع الخطأ: الأدوات بأسلوب OpenAI وSDK الخاص بـ OpenAI تأخذ العنوان مع /v1. أما Anthropic SDK وClaude Code فيأخذان العنوان بدون /v1: https://api.cheaptokens.dev.

إذا تساءلت يومًا ما هو base URL بالضبط وأي جزء منه تضيفه الأداة، هذا الشرح يستعرض ذلك. ولجانب Anthropic، راجع Anthropic Python SDK مع CheapTokens.

404 على نموذج واحد: معرّف النموذج#

هذا الخطأ يوقع من ينسخ اسمًا من جدول أسعار أو من مزوّد آخر. قد يقول جدول الأسعار DeepSeek-V4-Flash؛ لكن API يريد معرّف البوابة الكامل، مع بادئة المطوّر والإصدار:

أين رأيته ما يحتاجه API
DeepSeek-V4-Flash deepseek-ai/DeepSeek-V4-Flash-0731
GLM-5.3-Flash zai-org/GLM-5.3-Flash
MiniMax-M2.7 MiniMaxAI/MiniMax-M2.7

المعرّفات القصيرة من تسميات الأسعار لا يقبلها API، والتهجئة مهمة: الأحرف الكبيرة، والشرطة المائلة، ولاحقة -0731. انسخ المعرّف من وثائق CheapTokens بدلًا من كتابته من الذاكرة — مزوّدون مختلفون يسمّون النموذج نفسه بشكل مختلف. لرؤية المعرّفات الدقيقة المتاحة لمفتاحك، استدعِ GET https://api.cheaptokens.dev/v1/models مع نفس ترويسة Authorization وانسخ المعرّف من القائمة:

bash
curl https://api.cheaptokens.dev/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

إذا بدت منطقية الأسماء في الجدول غريبة، كيف تقرأ أسماء نماذج AI يشرح الفرق بين الاسم المستعار والإصدار المثبّت.

أثبت الإصلاح بأمر curl واحد#

أخرج الأداة من الصورة واستدعِ API مباشرة. استبدل العنصر النائب للمفتاح بمفتاحك:

bash
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-V4-Flash-0731",
    "messages": [{"role": "user", "content": "Say hi in one word."}],
    "max_tokens": 20
  }'

هذا الطلب الواحد يحتوي على المشتبه بهم الثلاثة: المفتاح في الترويسة، وbase URL في السطر الأول، ومعرّف النموذج في الجسم. رد JSON يحتوي على مصفوفة choices يعني أن الثلاثة صحيحة، وأن ما تفعله أداتك بشكل مختلف هو المشكلة. إذا فشل، غيّر شيئًا واحدًا في كل مرة:

  • 401 → استبدل المفتاح الذي حصلت عليه من CheapTokens وشغّل مرة أخرى.
  • 404 → قارن URL حرفًا بحرف مع المذكور أعلاه، ثم معرّف النموذج.

بعد أن ينجح curl، انسخ القيم الثلاث نفسها إلى الأداة: المفتاح، وbase URL (https://api.cheaptokens.dev/v1، أو بدون /v1 لـ Anthropic SDK وClaude Code) ومعرّف النموذج الكامل.

إذا لم يعمل بعد#

  • نفس الخطأ في الأداة، وcurl يعمل. الأداة تقرأ مفتاحًا أو URL قديمًا من مكان آخر: ملف إعدادات ثانٍ، أو ملف تعريف محفوظ، أو متغير بيئة. أعد تشغيل الأداة بعد تغييره.
  • لست متأكدًا أن معرّف النموذج صحيح. استدعِ GET /v1/models بمفتاحك وانسخ المعرّف من القائمة.
  • رفض الاتصال، أو المهلات، أو أخطاء الشهادات. هذا ليس 401 أو 404؛ راجع أخطاء الاتصال الشائعة.
  • لست متأكدًا كيف يجب أن يبدو الطلب الأول. طلبك الأول إلى API يسير خطوة بخطوة، والوثائق فيها المرجع الكامل.

العادة التي تستحق التمسك بها: عندما يفشل استدعاء، اقرأ الرقم أولًا. 401 عادةً يعني المفتاح، و404 عادةً العنوان أو معرّف النموذج، وcurl يحسم الأمر. هذا يحل معظم هذه الأخطاء قبل أن تفتح سجلًا واحدًا.

الوسوم: