تنقسم أخطاء DeepSeek API تقريبًا إلى أربعة أنواع: المصادقة، والمسار واسم الطراز، وتحديد المعدل، والمهلة. الترتيب الصحيح للتشخيص هو: اقرأ أولًا رمز حالة HTTP ونوع الخطأ، ثم معرّف الطلب وأصغر حالة إعادة إنتاج، وأخيرًا عدّل المطالبة أو غيّر الطراز. عكس الترتيب يجعل مشكلة إعدادات تبدو وكأنها مشكلة قدرات الطراز.

تقسم هذه المقالة الأخطاء إلى 401 و404 و429 والمهلة، وتعطي الأسباب وخطوات التشخيص وكود تراجع قابلًا لإعادة الاستخدام. الطرازات والأسعار تتبع أسعار الطرازات داخل الموقع.

ملاحظة: DeepSeek علامة تجارية تخص مالكها. قد تتغير أنواع الأخطاء وقواعد تحديد المعدل وسلوك الواجهة مع الإصدارات؛ تعتمد المقالة على الحالة الشائعة في أكتوبر 2026، والمرجع النهائي هو الوثائق الرسمية.

أولًا: ميّز الأنواع الأربعة أولًا

الحالة أو الظاهرة المعنى الشائع السبب النموذجي ترتيب المعالجة
401 فشل المصادقة مفتاح خاطئ أو غياب Bearer أو مفتاح منتهي صحّح بيانات الاعتماد أولًا
404 المسار أو الطراز غير موجود Base URL خاطئ أو اسم طراز قديم أو تكرار المسار افحص العنوان واسم الطراز
429 تحديد معدل أو حصة اندفاع تزامن أو مفتاح مشترك أو عاصفة إعادة محاولة تراجع وخفّض التزامن
المهلة مهلة اتصال أو قراءة الشبكة أو إخراج طويل أو طراز استدلالي أو وكيل تشخيص طبقي
400 معامل طلب أو سياق غير صالح تجاوز السياق أو تنسيق خاطئ قسّم بعد حساب الحجم
5xx خطأ في خدمة المزود عطل أو حمل زائد في الخادم تراجع وغيّر القناة

سجّل في السجلات على الأقل الوقت ورمز الحالة ونوع الخطأ واسم الطراز والزمن ومعرّف الطلب. لا تسجّل المفتاح كاملًا، ولا تطبع نص المستخدم بالكامل في السجلات.

ثانيًا: 401: افحص رأس الطلب ثم المفتاح

يعني 401 أن الهوية لم تُتحقق، وغالبًا لا علاقة له بقدرة الطراز أو الرصيد. اتبع الترتيب التالي:

  1. هل يستخدم رأس الطلب Authorization: Bearer <key> وليس طريقة مصادقة أخرى.
  2. هل توجد مسافات أو أسطر جديدة أو علامات اقتباس زائدة حول المفتاح. النسخ من نافذة محادثة هو السبب الأكثر شيوعًا.
  3. هل تم تحميل متغير البيئة فعلًا، يمكن طباعة البادئة فقط للتأكد.
  4. هل حُذف المفتاح أو أُعيد تدويره أو أُوقف.
  5. هل Base URL والمفتاح ينتميان إلى المنصة نفسها؛ مفتاح رسمي مع عنوان بوابة يعيد 401.
  6. هل الوكيل العكسي يحذف رأس Authorization أو يستبدله.
export DEEPSEEK_API_KEY="sk-مفتاحك"

curl "https://api.deepseek.com/chat/completions" \
  -H "Authorization: Bearer $DEEPSEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role": "user", "content": "أعد OK فقط"}],
    "max_tokens": 16
  }'

إذا أعاد هذا الأمر 200، فإن المفتاح وBase URL واسم الطراز سليمة. إذا بقي 401، جرّب مفتاحًا جديدًا بطلب أدنى للتمييز بين مشكلة المفتاح نفسه ومشكلة إعدادات الوكيل أو البوابة.

ثالثًا: 404: العنوان واسم الطراز هما الأكثر خطأً

غالبًا لا يعني 404 أن «الواجهة معطلة»، بل أن الطلب وصل إلى مسار أو طراز غير موجود. الأسباب الشائعة:

  • Base URL مكتوب كعنوان مزود آخر، أو /v1 زائد أو ناقص.
  • SDK يضيف /chat/completions تلقائيًا، ثم يُضاف المسار مرة أخرى يدويًا.
  • اسم الطراز إصدار قديم أُوقف، أو حالة الأحرف أو اللاحقة غير متطابقة.
  • خلط عنوان البوابة والعنوان الرسمي مع اختلاف قواعد المسار.
  • قواعد إعادة الكتابة في الوكيل العكسي أفسدت المسار.

ابدأ التشخيص بـcurl على العنوان الكامل، واقرأ رسالة الخطأ في جسم الاستجابة؛ ثم طابق Base URL واسم الطراز بندًا بندًا مع صفحة الأسعار. لا تثبّت عدة عناوين في الشيفرة، بل اضبطها حسب البيئة لمنع تسرب عنوان الاختبار إلى الإنتاج.

رابعًا: 429: تحديد المعدل ليس نقص رصيد

يعني 429 أن الطلبات تجاوزت حد السرعة أو التزامن أو الحصة. قد تطبق DeepSeek تحديد معدل أو طابورًا في الذروة، والقواعد الدقيقة حسب الوثائق الرسمية. الحالات الشائعة:

  • عدة خدمات تشترك في مفتاح واحد وتتنافس على الحصة.
  • مهام دفعية تبدأ في الساعة نفسها فتخلق اندفاع حركة.
  • إعادة المحاولة بلا تراجع، فتزيد الطلبات مع كل فشل وتصنع عاصفة.
  • مهام الإخراج الطويل أو الاستدلال تستهلك موارد أكثر، فتضيق مساحة التزامن.
الظاهرة السبب المحتمل المعالجة
429 مركّز في الذروة حمل المزود أو اندفاع حركة طابور وإرسال متدرج وتوزيع الأوقات
429 مع مفتاح واحد لعدة خدمات حصة مشتركة افصل المفاتيح حسب المشروع
يزداد سوءًا بعد إعادة المحاولة إعادة محاولة بلا تراجع تراجع أسي مع تذبذب عشوائي
الطلبات الطويلة تعيد 429 أولًا استهلاك Tokens الإخراج مرتفع خفّض max_tokens أو التزامن 
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError

client = OpenAI(
    api_key="sk-مفتاحك",
    base_url="https://api.deepseek.com",
    max_retries=0,  # أوقف إعادة المحاولة التلقائية في SDK لمنع التداخل
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="deepseek-chat",
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
                timeout=60,
            )
            return resp.choices[0].message.content
        except (RateLimitError, APITimeoutError):
            wait = min(2 ** attempt, 20) + random.random()
            print(f"المحاولة {attempt + 1} فشلت، الانتظار {wait:.1f} ثانية")
            time.sleep(wait)
        except APIStatusError as exc:
            if exc.status_code >= 500:
                wait = min(2 ** attempt, 20) + random.random()
                time.sleep(wait)
                continue
            raise
    raise RuntimeError("استُهلكت محاولات إعادة الإرسال")

print(ask("اشرح في جملة واحدة ما هو تحديد المعدل"))

إعادة المحاولة مناسبة فقط للأخطاء العابرة. الأعمال التي أنتجت أثرًا جانبيًا يجب أن تتحقق أولًا بمفتاح عدم تكرار أو فحص حالة قبل قرار الإعادة.

خامسًا: المهلة: ميّز الاتصال والقراءة والبث

المهلة لا تعني أن الخدمة غير متاحة، بل يجب تحديد المكان المتوقف:

الظاهرة السبب المحتمل المعالجة
مهلة اتصال DNS أو منفذ الشبكة أو وكيل غير قابل للوصول افحص الشبكة والوكيل وغيّر المسار
أول Token بطيء طابور المزود أو مطالبة طويلة اختصر المدخل ووزّع الأوقات واستخدم طرازًا أخف
مهلة قراءة إخراج طويل أو تفكير طويل في طراز استدلالي ارفع مهلة القراءة وحدّ الإخراج
انقطاع البث تقلب الشبكة أو انقطاع الوكيل ادعم إعادة الاتصال وسجّل المحتوى المستلم
مهلة متزامنة في كل الموقع منفذ محلي أو عطل المزود بدّل القناة وراقب حالة الخدمة 
import httpx
from openai import OpenAI

client = OpenAI(
    api_key="sk-مفتاحك",
    base_url="https://api.deepseek.com",
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)

يجب ضبط مهلة الاتصال ومهلة القراءة منفصلتين. ضبط كل المهل على قيمة كبيرة يجعل الأعطال تحتجز مجمع الخيوط؛ وضبطها صغيرًا جدًا يقتل المهام الطويلة الطبيعية. الضبط حسب نوع المهمة هو الأكثر أمانًا.

سادسًا: جدول ترتيب التشخيص

  1. سجّل رمز الحالة ونوع الخطأ ومعرّف الطلب واسم الطراز ووقت الحدوث.
  2. في 401 افحص المفتاح ورأس الطلب ومتغير البيئة وتطابق المنصة.
  3. في 404 افحص Base URL وتجميع المسار واسم الطراز.
  4. في 400 افحص المعاملات وطول السياق وتنسيق الصورة أو الملف.
  5. في 429 افحص التزامن والمفتاح المشترك وسياسة الإعادة وساعات الذروة.
  6. في المهلة افحص DNS والوكيل وطول الإخراج وإعداد مهلة القراءة.
  7. في 5xx تراجع وأعد المحاولة، وإذا استمر فأبلغ المزود مع معرّف الطلب.
  8. بعد كل عطل أضف مراقبة وتنبيهًا، ولا تنتظر شكوى المستخدم.

سابعًا: المراقبة والسجلات

الحقل الاستخدام
الوقت والمشروع تحديد الذروة ونطاق التأثير
رمز الحالة ونوع الخطأ التمييز بين المصادقة وتحديد المعدل وأخطاء المزود
معرّف الطلب دليل أساسي عند مخاطبة المزود
اسم الطراز وإصداره معرفة ما إذا ظهر الخطأ بعد تغيير الطراز
Tokens الإدخال والإخراج تحليل التكلفة والطلبات الطويلة
الزمن وعدد المحاولات اكتشاف تأخر الذيل وعاصفة الإعادة

يجب أن تجمع المراقبة على الأقل عدد 401 و404 و429 والمهل و5xx كل ساعة. عند ارتفاع معدل الأخطاء، افحص أولًا ما إذا كان التركيز في مشروع أو مفتاح أو طراز معين، ثم قرر خفض التزامن أو تبديل القناة أو الرجوع إلى إصدار سابق.

الأسئلة الشائعة

هل 429 يعني نقص الرصيد؟

لا. يعني 429 تجاوز حد السرعة أو التزامن أو الحصة، أما نقص الرصيد فيعيد عادةً خطأ آخر أو يوضح ذلك في جسم الاستجابة. افحص التزامن والمفتاح المشترك أولًا، ثم رصيد الحساب.

ما السبب الأكثر شيوعًا لـ404؟

Base URL خاطئ أو تكرار المسار أو اسم طراز منتهي. استخدم curl على العنوان الكامل، ثم طابق اسم الطراز مع صفحة الأسعار؛ عادةً يمكن تحديد السبب في دقائق.

هل يجب إعادة المحاولة بلا حد عند المهلة؟

لا. يجب أن يكون لإعادة المحاولة حد وتراجع وتنبيه، وقد تعني المهلة أن الطلب نُفذ فعليًا لدى المزود. الأعمال ذات الآثار الجانبية تتحقق من الحالة قبل الإعادة.

ماذا أفعل عند انقطاع الإخراج المتدفق؟

سجّل المحتوى المستلم وموضع الانقطاع، ثم ميّز بين تقلب الشبكة وانقطاع الوكيل ومهلة المزود. يجب أن يدعم العميل إعادة الاتصال وإزالة التكرار، ولا تُدخل محتوى ناقصًا كأنه نتيجة كاملة.

كيف أميّز خطأ البوابة من الخطأ الرسمي؟

احتفظ بمعرّف الطلب ونوع الخطأ، وأرسل الطلب نفسه إلى المدخل الرسمي والبوابة. يساعد ذلك على التمييز بسرعة بين المفتاح والشبكة وإعدادات البوابة وخدمة المزود.

الخطوة التالية

أنشئ مفتاح اختبار في ZSQH AI Gateway، ونفّذ تمرينًا على 401 و404 و429 والمهلة، ثم اربط مراقبة الإنتاج. توفر الطرازات والأسعار في أسعار الطرازات.

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