أخطاء المُسرِّع

النطاق

تُظهِر هذه الاستثناءات الخمسة الإخفاقات الواردة من العربة الجانبية الاختيارية لمُسرِّع العتاد ⁨Spectrum⁩ (⁨Prism⁩). يُتصل بالعربة الجانبية عبر ⁨HTTP⁩ من خلال NextPDF\Accelerator\SpectrumClient؛ وتحمل استجابات الخطأ رمزًا قابلًا للقراءة آليًا SPEC-* من تصنيف معياري، ويربط العميل ذلك الرمز بأحد أنواع الاستثناءات أدناه.

وخلافًا لمعظم استثناءات ⁨NextPDF⁩، لا تطبّق استثناءات المُسرِّع getContext(). فهي تمدّد فئة ⁨PHP⁩ المسماة RuntimeException وتكشف حالتها بوصفها خصائص عامة readonly ذات أنواع. ميّز مجالات الخطأ بمطابقة سابقة specCode (على سبيل المثال str_starts_with($e->specCode, 'SPEC-AUTH-'))، لا باعتراض الفئات الفرعية — فهرم الفئات الفرعية داخلي وقد يتغيّر في الإصدارات الثانوية.

SpectrumApiException

SpectrumApiException هو النوع الأساسي لكل استجابة خطأ من العربة الجانبية. يُطلَق مباشرةً لأي رمز SPEC-* ليس له فئة فرعية أكثر تحديدًا، وهو النوع الذي تعترضه لمعالجة كل أخطاء العربة الجانبية دفعةً واحدة.

متى يُطلَق

• تُرجع العربة الجانبية جسم خطأ مُنظَّم SPEC-*. يفكّ SpectrumResponseParser ترميز الجسم ويُطلق هذا النوع لكل الرموز عدا SPEC-AUTH-* وSPEC-OOM-* (اللذين يُربطان بفئتين فرعيتين أدناه). تشمل الربوط المُوثَّقة بهذا النوع الأساسي SPEC-INDEX-* (فهرس المجموعة)، وSPEC-KMS-* (مزوّد إدارة المفاتيح)، وSPEC-OCR-*، وSPEC-MODEL-*، وSPEC-BILLING-*.
• SPEC-IO-001 — جسم الاستجابة ليس ⁨JSON⁩ صالحًا (httpStatus 502).
• SPEC-IO-002 — إصدار واجهة ⁨API⁩ للعربة الجانبية غير متوافق مع minApiVersion المُهيّأ.
• SPEC-SEC-001 — تتجاوز حمولة مستند ميزانية الحجم المُهيّأة (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — يُخفق مسار مساحة عمل في فحص الاجتياز (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — مُعرِّف مهمة فارغ أو طويل أكثر من اللازم أو يحتوي محارف خارج قائمة سماح المُعرِّف المُبهَم (SpectrumSecurityPolicy::validateJobId()).

الخصائص

الخاصية	النوع	المعنى
specCode	string	رمز خطأ SPEC-* قابل للقراءة آليًا (على سبيل المثال SPEC-INDEX-003).
httpStatus	int	حالة ⁨HTTP⁩ التي أرجعتها العربة الجانبية؛ القيمة الافتراضية 500. وتُستخدم أيضًا بوصفها رمز الاستثناء.
retryable	bool	ما إذا كان يمكن إعادة محاولة العملية بأمان. القيمة الافتراضية false.
traceId	?string	مُعرِّف التتبّع للترابط من ترويسة الاستجابة X-Trace-Id، أو null.

تُؤلَّف الرسالة على هيئة "[{specCode}] {message}". وتُصنّف ثلاث محمولات مساعِدة المجالات الشائعة: isKmsError() (SPEC-KMS-*)، وisIndexError() (SPEC-INDEX-*)، وisOcrError() (SPEC-OCR-*).

التعافي

1. اقرأ specCode لتحديد المجال المُخفِق؛ وتفرّع بحسب سابقته.
2. احترِم retryable: أعد المحاولة فقط عندما تكون true، ولا تُعِدها أبدًا عند رمز SPEC-SEC-* أو SPEC-IO-002، اللذين يُشيران إلى عيوب في الإعداد أو التوافق.
3. التقط traceId في سجلاتك لربط الإخفاق بالتشخيصات على جانب العربة الجانبية في تقرير عيب.

فئات ⁨Spectrum⁩ الفرعية

الأنواع التالية فئات فرعية final من SpectrumApiException. اعترض SpectrumApiException (أو طابِق على specCode) بدلًا من اعتراضها مباشرةً.

SpectrumAuthenticationException

يُطلَق لرموز SPEC-AUTH-*، ويُشير إلى إخفاق في الترخيص أو الرمز المميَّز أو ربط النشر. يُطلقه SpectrumResponseParser كلما بدأ رمز الاستجابة بـSPEC-AUTH-.

تشمل الأسباب المُوثَّقة SPEC-AUTH-001 (توقيع ⁨Ed25519⁩ غير صالح للترخيص)، وSPEC-AUTH-002 (انتهاء صلاحية الترخيص وخروجه عن فترة السماح)، وSPEC-AUTH-003 (عدم تطابق خانة النشر)، وSPEC-AUTH-004 (رمز ⁨JWT⁩ المميَّز ⁨Bearer⁩ غير صالح)، وSPEC-AUTH-006 (الترخيص متدهور، وانتهت فترة السماح)، وSPEC-AUTH-007 (الميزة غير مُضمَّنة في الترخيص المُشترى).

يحمل الخصائص نفسها للنوع الأساسي، لكن المُنشئ يثبّت retryable على false ويجعل القيمة الافتراضية لـhttpStatus هي 403.

التعافي. هذه الأخطاء ليست قابلة لإعادة المحاولة أبدًا من دون تدخّل المُشغِّل. جدّد الترخيص أو صحّحه، أو حدّث الرمز المميَّز ⁨Bearer⁩، أو واءِم خانة النشر، ثم أعد تشغيل الاستدعاء.

SpectrumResourceException

يُطلَق لرموز SPEC-OOM-* عند نفاد ذاكرة وحدة معالجة الرسوميات (⁨GPU⁩) أو وحدة المعالجة المركزية (⁨CPU⁩). يُطلقه SpectrumResponseParser لأي سابقة SPEC-OOM-، ويُطلقه إعداد DegradePolicy::FailFast بدلًا من التدهور بصمت إلى مستوى عتاد أدنى.

يثبّت المُنشئ retryable على true ويجعل القيمة الافتراضية لـhttpStatus هي 503.

التعافي. هذا الاستثناء قابل لإعادة المحاولة. ضع المهمة في الطابور وأعد المحاولة بعد اكتمال المهام الأخرى وتحرير الموارد، أو خفّف DegradePolicy إلى AllowWithLog / WarnAndProceed إن كان مستوى مُخفَّض مقبولًا لعبء العمل.

SpectrumProtocolException

يُطلَق عندما تُحلَّل استجابة العربة الجانبية بوصفها ⁨JSON⁩ لكنها لا تطابق شكل البروتوكول المتوقَّع. يستخدم دائمًا specCode المساوي لـSPEC-IO-003 وhttpStatus المساوي لـ502، مع تثبيت retryable على false.

وهذا متميّز عن SPEC-IO-001 (⁨JSON⁩ غير صالح): فهنا ⁨JSON⁩ سليم الشكل لكنه خاطئ بنيويًا، ما يُشير عادةً إلى وسيط أو بوابة تُعيد كتابة الجسم، أو إصدار غير متوافق للعربة الجانبية، أو استجابة تالفة.

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

SpectrumNotAvailableException

SpectrumNotAvailableException تمدّد RuntimeException مباشرةً وليست جزءًا من هرم SpectrumApiException. وتُشير إلى أن العربة الجانبية غير قابلة للوصول أو أخفقت في فحص صحة، قبل أن يُرجَع أي جسم خطأ SPEC-*.

متى يُطلَق

• قاطع الدارة مفتوح، أو استُنفدت كل محاولات إعادة المحاولة (SpectrumClient).
• يقع خطأ نقل ⁨HTTP⁩ أثناء الاتصال بالعربة الجانبية؛ ويُسلسَل ⁨PSR⁩-18 ClientExceptionInterface الأساسي بوصفه الاستثناء السابق.
• يُطلَب دفق أحداث مُرسَلة من الخادم بينما تُبلّغ العربة الجانبية عن أنها غير متاحة (SseStreamClient).

الخصائص

لا يحمل هذا النوع أي بيانات وصفية SPEC-*. تُؤلَّف الرسالة على هيئة "Spectrum sidecar unavailable: {reason}"، مع عدد صحيح اختياري code وقابل للإطلاق سابق مُتسلسل previous.

التعافي

اعترض هذا عندما يكون ⁨Spectrum⁩ اختياريًا واسقط احتياطيًا إلى المعالجة المحلية بـ⁨PHP⁩ (تدهور لطيف). وعندما يكون ⁨Spectrum⁩ مطلوبًا، فتأكّد من أن العربة الجانبية تعمل وقابلة للوصول، ثم أعد تشغيل الاستدعاء.

انظر أيضًا

• فهرس مرجع الأخطاء
• التشفير والأذونات
• فهرس قاعدة المعرفة