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

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

ملاحظة: Zhipu وGLM وBigModel علامات تجارية تخص أصحابها، وهذه المقالة للتوضيح التقني فقط، ولا توجد علاقة تبعية أو وكالة مع Zhipu. قد تتغير رموز الأخطاء وقواعد التحديد وسلوك الواجهة مع الإصدارات، والمرجع النهائي الوثائق الرسمية والاستجابة الفعلية.

أولًا: ميّز طبقتي الخطأ أولًا

رمز حالة HTTP يوضح نتيجة طبقة البروتوكول، ورمز العمل يوضح السبب المحدد. قد يكون 401 نفسه بسبب غياب رأس المصادقة أو انتهاء Token أو مصادقة ثانية؛ وقد يكون 429 نفسه بسبب التحديد أو انشغال الطراز أو المتأخرات أو سقف الباقة. تسجيل رمز العمل في السجلات هو الخطوة الأكثر فاعلية في التشخيص.

HTTP رموز العمل الشائعة المعنى هل يصلح إعادة المحاولة
401 1000 / 1001 / 1003 / 1005 فشل المصادقة أو غياب الرأس أو انتهاء Token أو مصادقة ثانية لا، صحّح بيانات الاعتماد أولًا
403 1220 لا صلاحية للوصول إلى API أو الطراز لا، افحص الباقة والصلاحيات
400 1210 / 1211 / 1221 / 1222 / 1261 معامل خاطئ أو طراز غير موجود أو API موقوف أو غير موجود أو مطالبة طويلة لا، عدّل الطلب
429 1113 متأخرات على الحساب لا، اشحن أولًا
429 1302 / 1305 تحديد سرعة أو حمل وصول مرتفع على الطراز نعم، بعد التراجع
429 1308 / 1310 سقف الدورة، يتجدد حسب next_flush_time انتظر التجديد ولا تُعد بعناد
429 1311 / 1313 / 1315 الباقة بلا صلاحية طراز أو حد استخدام عادل أو نوع مفتاح غير مطابق لا، افحص الباقة والمفتاح
500 1200 / 1230 / 1234 خطأ داخلي أو خطأ سير أو خطأ شبكة مع معرّف خطأ نعم، تراجع واحتفظ بمعرّف الخطأ

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

ثانيًا: 401: أربعة أنواع من فشل المصادقة

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

  • 1000 فشل التحقق: مفتاح خاطئ أو نسخ ناقص أو مفتاح محذوف.
  • 1001 غياب معامل المصادقة في الرأس: لا يوجد Authorization: Bearer <key> أو حذفه الوكيل.
  • 1003 انتهاء Token: للمفتاح مدة صلاحية أو أُعيد تدويره في لوحة التحكم.
  • 1005 المصادقة الثنائية مفعّلة: أكمل التحقق وفق متطلبات المنصة.

نفّذ التشخيص بالترتيب:

  1. تأكد من تنسيق رأس الطلب: مسافة واحدة بعد النقطتين، وبلا اقتباسات أو أسطر جديدة حول المفتاح.
  2. اطبع بادئة متغير البيئة للتأكد من أنه ليس فارغًا أو قديمًا.
  3. تأكد من نوع المفتاح: مفاتيح API القياسية وCoding Plan والفرق والمؤسسة تُدار منفصلة ولا تخلط.
  4. تأكد من تطابق Base URL مع المفتاح: مفتاح رسمي مع عنوان رسمي، ومفتاح بوابة مع عنوان بوابة.
  5. جرّب مفتاحًا جديدًا بطلب أدنى للتمييز بين مشكلة المفتاح ومشكلة الوكيل أو البوابة.

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

ثالثًا: 403 و404: الصلاحية والمسار واسم الطراز

رمز العمل الشائع لـ403 هو 1220، ويعني أن الحساب الحالي لا يملك صلاحية الوصول إلى API أو الطراز. افحص أولًا هل تتضمن الباقة الطراز، وهل المفتاح من نوع المنتج المطابق، ثم هل تُستدعى واجهة غير مفعّلة. إعادة المحاولة بلا فائدة هنا؛ عدّل الصلاحية أو غيّر المفتاح.

404 في الغالب ليس «تعطل الخدمة»، بل عنوان خاطئ: Base URL بزيادة أو نقص /v1، أو SDK يضيف المسار ثم يُكتب المسار الكامل يدويًا مرة أخرى، أو قاعدة إعادة كتابة في الوكيل العكسي أفسدت المسار. اسم الطراز الخاطئ في GLM يعيد عادةً 400 مع 1211، وAPI الموقوف أو غير الموجود يقابل 1221 و1222. لذلك عند رؤية 404 افحص العنوان، وعند رؤية 1211 افحص اسم الطراز.

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

رابعًا: 429: اقرأ رمز العمل ثم قرر الإعادة

429 من أكثر الأخطاء عرضةً لسوء المعالجة، ويشمل خمس حالات على الأقل:

  • 1113 متأخرات على الحساب: إعادة المحاولة قبل الشحن بلا معنى.
  • 1302 بلوغ حد السرعة: خفّض التزامن أو تراجع.
  • 1305 حمل وصول مرتفع على الطراز: يرتبط عادةً بالذروة، تراجع وأعد المحاولة وبدّل الطراز عند الحاجة.
  • 1308 و1310 بلوغ سقف الدورة: تحتوي الرسالة وقت التجديد، فانتظر استعادة الحصة.
  • 1309 و1311 و1313 و1315: انتهاء الباقة أو عدم فتح الطراز أو حد الاستخدام العادل أو عدم تطابق نوع المفتاح، والتعديل وحده يفيد.

فقط التحديد اللحظي مثل 1302 و1305 يصلح لإعادة المحاولة التلقائية؛ إعادة المحاولة في الحالات الأخرى تطيل زمن العطل. قواعد التحديد (التزامن أو الطلبات في الدقيقة أو سرعة Tokens) تتغير مع الباقة والطراز، والمرجع لوحة التحكم والوثائق الرسمية.

خامسًا: 5xx والمهلة: تحديد منفصل

تشمل سلسلة 500 الرموز 1200 خطأ داخلي و1230 خطأ سير و1234 خطأ شبكة. يحمل 1234 عادةً معرّف خطأ يجب الاحتفاظ به عند التواصل مع الدعم. عند استمرار 5xx، تراجع أولًا ثم راجع حالة الخدمة أو إشعار المزود، ولا تُعد المحاولة بكثافة.

تُقسم المهلة إلى ثلاث مراحل: مهلة الاتصال تعني DNS أو منفذًا أو وكيلًا غير قابل للوصول؛ وبطء أول Token يعني عادةً طابور المزود أو إدخالًا طويلًا؛ ومهلة القراءة تعني غالبًا إخراجًا طويلًا أو تفكيرًا مطولًا. المعالجة تختلف، ولا يجوز فقط تكبير قيمة المهلة.

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

سادسًا: معرّف الطلب والسجلات: دليل التشخيص

لا توفر الاستجابة الرسمية بالضرورة معرّف طلب بالاسم نفسه في كل واجهة، والمرجع الاستجابة الفعلية والوثائق. الأكثر أمانًا هندسيًا تسجيل مزدوج: يولّد العميل trace_id يمتد عبر كل المحاولات؛ وتُحفظ في الوقت نفسه الاستجابة الخام من المزود وأي حقل request id أو error id فيها.

تتضمن السجلات على الأقل: الوقت وtrace_id وBase URL واسم الطراز ورمز HTTP ورمز العمل ورسالة الخطأ والزمن وعدد المحاولات وهل الطلب متدفق. يُسجل المفتاح بأوله أو بصمته فقط، ولا يُحفظ نص المستخدم أو الاستجابة الكاملة على القرص.

هذه الحقول ليست للفريق فقط. عند التواصل مع الدعم، سجل يحمل trace_id ورمز العمل وطلب إعادة إنتاج أدنى أنفع بكثير من عبارة «يحدث خطأ أحيانًا».

سابعًا: إعادة المحاولة والتراجع: مثال كود

يوقف الكود التالي إعادة المحاولة التلقائية في SDK، ويقرر الإعادة حسب رمز العمل، ويطبع trace_id ورمز الحالة ورمز العمل معًا. تُعالج مهلة الشبكة منفصلة، ولإعادة المحاولة حد أقصى.

import os
import random
import time
import uuid

import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError

client = OpenAI(
    api_key=os.environ["GLM_API_KEY"],
    base_url=os.environ.get(
        "GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
    ),
    timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
    max_retries=0,  # أوقف إعادة المحاولة التلقائية، والتحكم للمنطق أدناه
)

RETRYABLE_CODES = {1302, 1305}  # تحديد السرعة وانشغال الطراز؛ المتأخرات وسقف الباقة ليسا هنا

def ask(prompt: str, max_attempts: int = 4) -> str:
    trace_id = uuid.uuid4().hex[:12]
    for attempt in range(1, max_attempts + 1):
        try:
            resp = client.chat.completions.create(
                model=os.environ["GLM_MODEL"],
                messages=[{"role": "user", "content": prompt}],
                max_tokens=1024,
            )
            return resp.choices[0].message.content
        except APIStatusError as exc:
            code = None
            try:
                code = int(exc.response.json().get("code"))
            except Exception:
                pass
            print(
                f"trace={trace_id} attempt={attempt} "
                f"http={exc.status_code} code={code} "
                f"body={exc.response.text[:500]}"
            )
            retryable = exc.status_code >= 500 or (
                exc.status_code == 429 and code in RETRYABLE_CODES
            )
            if not retryable or attempt == max_attempts:
                raise
        except (APITimeoutError, APIConnectionError) as exc:
            print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
            if attempt == max_attempts:
                raise
        wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
        time.sleep(wait)
    raise RuntimeError("استُهلكت محاولات إعادة الإرسال")

ثلاث قواعد إضافية: احترم Retry-After الذي يعيده الخادم إن وجد؛ واضبط ميزانية الإعادة عالميًا لتجنب تراكم الخدمات؛ وللطلبات ذات الآثار الجانبية تحقق بمفتاح عدم تكرار قبل قرار الإعادة.

ثامنًا: حوكمة التزامن: أنفع من تكبير عدد المحاولات

مشكلة التحديد لا تُحل عادةً بإعادة المحاولة، بل بحوكمة المدخل:

  • مفتاح مستقل وسقف تزامن لكل خدمة.
  • تقسيم المهام الدفعية وتوزيع أوقاتها لمنع اندفاع الساعة نفسها.
  • طابور لتسوية الذروة، وإدخال المهام الفاشلة في طابور مؤجل بدل الدوران في المكان.
  • مراقبة نسبة 429 وتأخير P95، وخفض التزامن أولًا عند الارتفاع المفاجئ.
  • تجهيز طراز أو مدخل بديل، مع التحقق من توافق المعاملات قبل التبديل.

قيم سقف التزامن والطلبات في الدقيقة وسرعة Tokens تتغير مع الباقة والطراز، والمرجع لوحة التحكم والوثائق الرسمية. لا تنسخ أرقام الآخرين، بل اضبطها من قياسك الفعلي.

تاسعًا: قائمة تحقق قبل التواصل مع الدعم

  1. وقت الحدوث والمنطقة الزمنية، وهل العطل مركز.
  2. Base URL ومسار الواجهة واسم الطراز وطريقة الطلب.
  3. رمز HTTP ورمز العمل ورسالة الخطأ الكاملة.
  4. معرّف الخطأ أو الطلب؛ وإن لم يوجد فـtrace_id الذي ولّدته.
  5. طلب curl أدنى قابل لإعادة الإنتاج مع إخفاء المفتاح.
  6. هل الطلب متدفق وهل السياق طويل وهل عُدّلت الإعدادات حديثًا.
  7. نطاق التأثير: مفتاح واحد أو مشروع واحد أو كل الخدمات.

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

عاشرًا: الأسئلة الشائعة

هل 429 يعني دائمًا تحديد المعدل؟

لا. قد يكون 429 متأخرات (1113) أو سقف دورة (1308 و1310) أو باقة بلا صلاحية طراز (1311) أو حد استخدام عادل (1313). اقرأ رمز العمل أولًا، ثم قرر التراجع أو الشحن أو تعديل الإعدادات.

ماذا أفعل إذا فشل 401 حتى بعد تغيير المفتاح؟

تحقق من رأس الطلب Authorization: Bearer <key>، وتحميل متغير البيئة، وتطابق نوع المفتاح مع الواجهة، وتطابق Base URL مع المفتاح، وهل يحذف الوكيل العكسي رأس المصادقة.

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

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

كيف أشخّص انقطاع الإخراج المتدفق؟

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

ماذا أفعل إذا كانت الرسالة تحمل رمز حالة بلا رمز عمل؟

احتفظ بجسم الاستجابة والرؤوس كاملين، وسجّل trace_id وBase URL واسم الطراز وطلب إعادة إنتاج أدنى، ثم تواصل مع المزود. عند المرور ببوابة، قدّم لها هذه المعلومات أيضًا لمطابقة سجلات المزود.

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

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

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