Ошибки Accelerator

Область применения

Эти пять исключений выявляют сбои опционального сопроводителя-ускорителя оборудования Spectrum (Prism). К сопроводителю обращаются по HTTP через NextPDF\Accelerator\SpectrumClient; ответы об ошибках несут машиночитаемый код SPEC-* из канонической таксономии, и клиент сопоставляет этот код с одним из типов исключений ниже.

В отличие от большинства исключений NextPDF, исключения Accelerator не реализуют 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 — идентификатор задания пуст, слишком длинный или содержит символы вне списка разрешённых для непрозрачного ID (SpectrumSecurityPolicy::validateJobId()).

Свойства

Свойство	Тип	Значение
specCode	string	Машиночитаемый код ошибки SPEC-* (например SPEC-INDEX-003).
httpStatus	int	HTTP-статус, который вернул сопроводитель; по умолчанию 500. Также используется как код исключения.
retryable	bool	Можно ли безопасно повторить операцию. По умолчанию false.
traceId	?string	Корреляционный trace ID из заголовка ответа 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 (недопустимый Bearer-токен JWT), 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 связано как предыдущее исключение.
• Запрошен поток server-sent-events, пока сопроводитель сообщает о себе как о недоступном (SseStreamClient).

Свойства

Этот тип не несёт метаданных SPEC-*. Сообщение составляется как "Spectrum sidecar unavailable: {reason}", с необязательным целочисленным code и связанным previous-throwable.

Восстановление

Перехватывайте это, когда Spectrum опционален, и откатывайтесь к нативной обработке PHP (плавная деградация). Когда Spectrum обязателен, подтвердите, что сопроводитель поднят и доступен, затем повторно запустите вызов.

См. также

• Указатель справочника по ошибкам
• Шифрование и разрешения
• Указатель базы знаний