في أخطاء Kimi API، افحص ثلاثة أشياء أولًا: رمز حالة HTTP، وerror.type، وrequest_id. قد يكون 429 حملًا زائدًا على الخادم أو تحديد معدل على مستوى المؤسسة أو رصيدًا غير كافٍ؛ وقد يكون 401 مفتاحًا خاطئًا أو خلطًا بين الموقع الصيني والدولي. صنّف أولًا، ثم عدّل الشيفرة.

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

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

أولًا: جدول مرجعي سريع لرموز الحالة

رمز الحالة نوع الخطأ المعنى الشائع اتجاه المعالجة
400 invalid_request_error معامل خاطئ أو سياق طويل أو تجاوز حد الإخراج عدّل الطلب
400 content_filter المدخل أو المخرج خالف أمان المحتوى عدّل المطالبة
401 invalid_authentication_error مفتاح غير صالح أو منطقة غير متطابقة صحّح بيانات الاعتماد
401 incorrect_api_key_error مفتاح مفقود أو خاطئ صحّح بيانات الاعتماد
403 permission_denied_error واجهة غير مفتوحة أو قائمة IP أو رصيد أو صلاحية افحص الصلاحية والرصيد
404 resource_not_found_error اسم طراز أو مسار خاطئ افحص قائمة الطرازات
429 engine_overloaded_error حمل زائد على الخادم تراجع وأعد المحاولة
429 rate_limit_reached_error تجاوز التزامن أو RPM أو TPM أو TPD خفّض أو ارفع الحصة
429 exceeded_current_quota_error متأخرات أو رصيد غير كافٍ أو قسيمة منتهية اشحن الرصيد
499 client_closed_request العميل أو الوكيل أغلق الطلب مبكرًا افحص المهلة والبث
500 server_error خطأ داخلي في الخادم تراجع وأعد المحاولة
503 server_unavailable الخدمة غير متاحة مؤقتًا تراجع وأعد المحاولة
504 Gateway Time-out انتظار طويل للطلب استخدم البث

قد يظهر نقص الرصيد كـ403 أو 429 حسب المدخل، فلا تحكم برمز الحالة وحده بل بـerror.type. سجّل في السجلات الوقت ورمز الحالة ونوع الخطأ واسم الطراز وrequest_id على الأقل، ولا تسجّل المفتاح الكامل أو المحتوى الحساس.

ثانيًا: 401 — افحص المنطقة ثم المفتاح

  1. هل مفتاح الموقع الصيني موضوع مع عنوان الموقع الدولي أو العكس؟ الحساب والرصيد والمفتاح في الموقعين مستقلان تمامًا.
  2. هل اختلطت مفاتيح خطوط منتجات مختلفة، مثل منصة المطورين وKimi Code والعضوية؟
  3. هل توجد مسافات أو أسطر جديدة أو علامات اقتباس زائدة حول المفتاح؟
  4. هل متغير البيئة محمّل فعلًا؟ يمكن طباعة البادئة فقط للتأكد.
  5. هل حُذف المفتاح أو دُوّر أو فقد صلاحية المشروع الحالي؟
  6. هل الترويسة Authorization: Bearer <key> والمسار /v1/chat/completions؟
export MOONSHOT_API_KEY="مفتاحك"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "أجب بـ OK فقط"}]
  }'

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

ثالثًا: 404 — اسم الطراز وbase_url الأكثر خطأً

404 لا يعني بالضرورة إيقاف الطراز؛ هناك أربعة أسباب شائعة:

  • استخدام OpenAI SDK دون ضبط base_url، فتذهب الطلبات إلى عنوان OpenAI الافتراضي وتعيد أن الطراز غير موجود.
  • خطأ إملائي في اسم الطراز، أو استخدام طراز لا يملك الحساب صلاحيته حاليًا.
  • زيادة أو نقص /v1 في المسار، أو كتابة مسار الدردشة بشكل آخر.
  • اختلاف أسماء الطرازات والصلاحيات بين الموقع الصيني والدولي.

اسحب قائمة الطرازات بالمفتاح نفسه لتعرف ما يراه الحساب:

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

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

رابعًا: 429 — ثلاثة أنواع بمعالجات مختلفة

error.type المعنى هل يمكن إعادة المحاولة المعالجة
engine_overloaded_error حمل زائد على الخادم نعم تراجع وفق Retry-After وخفّض التزامن
rate_limit_reached_error تجاوز التزامن أو RPM أو TPM أو TPD على مستوى المؤسسة جزئيًا خفّض السرعة أو قسّم المفاتيح أو ارفع الفئة
exceeded_current_quota_error متأخرات أو رصيد غير كافٍ أو قسيمة منتهية لا اشحن أو افحص الفاتورة

تجاوز TPD يُعالج عادةً بالانتظار إلى اليوم التالي أو رفع الحصة، ولا معنى لإعادة المحاولة. الطلبات المقطوعة بـ429 لا تُحتسب عادةً، لكن المحاولة الناجحة تُحتسب؛ لا تعد بلا نهاية خوفًا من التكلفة، ولا تظن أن 429 يعني خصم المبلغ. يعيد OpenAI SDK المحاولة تلقائيًا افتراضيًا، وقد يضخم 429 واحدًا إلى عدة طلبات، لذا في الإنتاج اضبط max_retries صراحةً واستخدم منطق تراجع خاصًا بك.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="مفتاحك",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("الرصيد أو الحصة غير كافية، اشحن أولًا")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "انتظار", round(wait, 1), "ثانية")
            time.sleep(wait)
    raise RuntimeError("استُنفدت محاولات إعادة الإرسال")

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

خامسًا: المهلة و504

تظهر المهلة غالبًا في توليد النصوص الطويلة وتحليل المستندات الطويلة ووكلاء الشيفرة. ترتيب المعالجة:

  1. حوّل غير المتدفق إلى stream=True ليبقى الاتصال عائدًا ببيانات.
  2. اضبط مهلة اتصال ومهلة قراءة مناسبتين، ولا تستخدم قيم SDK الافتراضية.
  3. افحص وكيل الشركة والبوابة وأدوات التوجيه المحلية، فقد تقطع الاتصال مبكرًا وتظهر كـ499.
  4. استخدم max_completion_tokens للتحكم في طول الإخراج، وقسّم المهام الطويلة.
  5. سجّل معرّف الطلب ومدة كل مهلة لتمييز بطء الطراز من بطء الشبكة أو البوابة.
stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "اكتب قائمة تحقق للنشر"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

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

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

  1. سجّل رمز الحالة وerror.type وrequest_id واسم الطراز ووقت الحدوث.
  2. لـ401 و403: افحص المنطقة والمفتاح وخط المنتج والصلاحية والرصيد.
  3. لـ404: افحص base_url واسم الطراز وصلاحية الحساب، وتحقق بقائمة الطرازات.
  4. لـ400: افحص طول السياق وحد الإخراج وتنسيق الملف وأمان المحتوى.
  5. لـ429: صنّف حسب error.type إلى حمل زائد أو تحديد معدل أو نقص رصيد.
  6. لـ499 و504: افحص البث والمهلة والوكيل واستمرار الاتصال.
  7. لـ500 و503: تراجع وأعد المحاولة، وإذا استمر فأرسل request_id إلى المزود.
  8. بعد كل عطل، أضف مراقبة وتنبيهًا، ولا تنتظر ملاحظات المستخدمين.

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

ما الفرق بين 429 و503؟

قد يكون 429 حملًا زائدًا على الخادم أو مشكلة حصة أو رصيد، فافحص error.type أولًا؛ أما 503 فيعني عدم توفر الخدمة مؤقتًا ويُعالج عادةً بالتراجع وإعادة المحاولة. القاسم المشترك هو عدم إعادة المحاولة بفاصل ثابت وبشكل عنيف.

بعد الشحن ما زال 401، ماذا أفعل؟

تأكد أولًا من أن الشحن والمفتاح في المنطقة نفسها وخط المنتج نفسه. جرّب مفتاحًا جديدًا لاستبعاد حذف المفتاح القديم أو تخزين متغير البيئة.

أي خطأ يظهر عند تجاوز السياق؟

عادةً 400 invalid_request_error مع ذكر طول رموز الإدخال في الرسالة. قصّر المدخل أو اقتطع السجل أو استخدم طرازًا بسياق أكبر.

هل أفعّل إعادة المحاولة التلقائية في SDK؟

يمكن تفعيلها مع سقف. قد تضخم إعادة المحاولة الافتراضية 429، لذا يُنصح في الإنتاج بإيقافها وتنفيذ تراجع أسي وتنبيه حسب نوع الخطأ.

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

أرسل الطلب نفسه إلى المباشر وإلى البوابة، وقارن رمز الحالة وerror.type وrequest_id. يحدد ذلك بسرعة ما إذا كانت المشكلة في المصدر أو الشبكة أو المفتاح أو إعداد البوابة.

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

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

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