Błędy akceleratora

Zakres

Tych pięć wyjątków ujawnia awarie z opcjonalnego pomocniczego procesu (sidecar) akceleratora sprzętowego Spectrum (Prism). Sidecar jest osiągany przez HTTP za pośrednictwem NextPDF\Accelerator\SpectrumClient; odpowiedzi z błędami niosą czytelny maszynowo kod SPEC-* z kanonicznej taksonomii, a klient odwzorowuje ten kod na jeden z poniższych typów wyjątków.

W odróżnieniu od większości wyjątków NextPDF wyjątki akceleratora nie implementują getContext(). Rozszerzają RuntimeException PHP i udostępniają swój stan jako typowane, publiczne właściwości readonly. Rozróżniaj domeny błędów, dopasowując prefiks specCode (na przykład str_starts_with($e->specCode, 'SPEC-AUTH-')), a nie przechwytując podklasy — hierarchia podklas jest wewnętrzna i może się zmienić w wersjach pobocznych.

SpectrumApiException

SpectrumApiException to typ bazowy dla każdej odpowiedzi z błędem sidecara. Jest zgłaszany bezpośrednio dla każdego kodu SPEC-*, który nie ma bardziej szczegółowej podklasy, i jest typem, który przechwytujesz, aby obsłużyć wszystkie błędy sidecara naraz.

Kiedy jest zgłaszany

• Sidecar zwraca ustrukturyzowane ciało błędu SPEC-*. SpectrumResponseParser dekoduje ciało i zgłasza ten typ dla wszystkich kodów z wyjątkiem SPEC-AUTH-* oraz SPEC-OOM-* (które odwzorowują się na poniższe podklasy). Udokumentowane odwzorowania na ten typ bazowy obejmują SPEC-INDEX-* (indeks kolekcji), SPEC-KMS-* (dostawca zarządzania kluczami), SPEC-OCR-*, SPEC-MODEL-* oraz SPEC-BILLING-*.
• SPEC-IO-001 — ciało odpowiedzi nie jest prawidłowym JSON (httpStatus 502).
• SPEC-IO-002 — wersja API sidecara jest niezgodna ze skonfigurowanym minApiVersion.
• SPEC-SEC-001 — ładunek dokumentu przekracza skonfigurowany budżet rozmiaru (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — ścieżka obszaru roboczego nie przechodzi kontroli przechodzenia (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — identyfikator zadania jest pusty, zbyt długi lub zawiera znaki spoza listy dozwolonej dla nieprzezroczystego ID (SpectrumSecurityPolicy::validateJobId()).

Właściwości

Właściwość	Typ	Znaczenie
specCode	string	Czytelny maszynowo kod błędu SPEC-* (na przykład SPEC-INDEX-003).
httpStatus	int	Status HTTP zwrócony przez sidecar; domyślnie 500. Używany również jako kod wyjątku.
retryable	bool	Czy operacja może być bezpiecznie ponowiona. Domyślnie false.
traceId	?string	Identyfikator śledzenia korelacji z nagłówka odpowiedzi X-Trace-Id lub null.

Komunikat jest składany jako "[{specCode}] {message}". Trzy predykaty pomocnicze klasyfikują typowe domeny: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) oraz isOcrError() (SPEC-OCR-*).

Naprawa

1. Odczytaj specCode, aby zidentyfikować zawodzącą domenę; rozgałęziaj logikę na jej prefiksie.
2. Uwzględnij retryable: ponawiaj tylko wtedy, gdy ma wartość true, i nigdy dla kodu SPEC-SEC-* ani SPEC-IO-002, które sygnalizują defekty konfiguracji lub zgodności.
3. Przechwyć traceId w swoich logach, aby skorelować awarię z diagnostyką po stronie sidecara w raporcie o usterce.

Podklasy Spectrum

Poniższe typy to podklasy final SpectrumApiException. Przechwytuj SpectrumApiException (lub dopasowuj na specCode), a nie te bezpośrednio.

SpectrumAuthenticationException

Zgłaszany dla kodów SPEC-AUTH-*, wskazujących awarię licencji, tokenu lub powiązania wdrożenia. SpectrumResponseParser zgłasza go, gdy kod odpowiedzi zaczyna się od SPEC-AUTH-.

Udokumentowane przyczyny obejmują SPEC-AUTH-001 (nieprawidłowy podpis Ed25519 licencji), SPEC-AUTH-002 (licencja wygasła i poza okresem karencji), SPEC-AUTH-003 (niezgodność slotu wdrożenia), SPEC-AUTH-004 (nieprawidłowy token JWT Bearer), SPEC-AUTH-006 (licencja zdegradowana, karencja wygasła) oraz SPEC-AUTH-007 (funkcja nieuwzględniona w zakupionej licencji).

Niesie te same właściwości co typ bazowy, ale konstruktor przypina retryable do false i domyślnie ustawia httpStatus na 403.

Naprawa. Te błędy nigdy nie są ponawialne bez interwencji operatora. Odnów lub popraw licencję, odśwież token Bearer albo wyrównaj slot wdrożenia, a następnie ponownie uruchom wywołanie.

SpectrumResourceException

Zgłaszany dla kodów SPEC-OOM-*, gdy pamięć GPU lub CPU jest wyczerpana. SpectrumResponseParser zgłasza go dla każdego prefiksu SPEC-OOM-, a ustawienie DegradePolicy::FailFast zgłasza go zamiast po cichu obniżać do niższego poziomu sprzętowego.

Konstruktor przypina retryable do true i domyślnie ustawia httpStatus na 503.

Naprawa. Ten wyjątek jest ponawialny. Umieść zadanie w kolejce i ponów po ukończeniu innych zadań i zwolnieniu zasobów albo złagodź DegradePolicy do AllowWithLog / WarnAndProceed, jeśli obniżony poziom jest akceptowalny dla danego obciążenia.

SpectrumProtocolException

Zgłaszany, gdy odpowiedź sidecara parsuje się jako JSON, ale nie pasuje do oczekiwanego kształtu protokołu. Zawsze używa specCode SPEC-IO-003 oraz httpStatus 502, z retryable przypiętym do false.

To różni się od SPEC-IO-001 (nieprawidłowy JSON): tutaj JSON jest poprawnie sformowany, ale strukturalnie błędny, co zwykle wskazuje na proxy lub bramę przepisującą ciało, niezgodną wersję sidecara lub uszkodzoną odpowiedź.

Naprawa. Nieponawialny — kształt odpowiedzi jest deterministyczny dla danej wersji sidecara. Zweryfikuj wersję sidecara względem minApiVersion klienta, sprawdź każde pośredniczące proxy lub bramę, a następnie ponownie wdróż zgodny sidecar.

SpectrumNotAvailableException

SpectrumNotAvailableException rozszerza RuntimeException bezpośrednio i nie jest częścią hierarchii SpectrumApiException. Sygnalizuje, że sidecar jest nieosiągalny lub nie przeszedł kontroli kondycji, zanim mogłoby zostać zwrócone jakiekolwiek ciało błędu SPEC-*.

Kiedy jest zgłaszany

• Wyłącznik obwodu jest otwarty lub wszystkie próby ponowienia zostały wyczerpane (SpectrumClient).
• Podczas kontaktu z sidecarem występuje błąd transportu HTTP; bazowy ClientExceptionInterface PSR-18 jest powiązany jako poprzedni wyjątek.
• Zażądano strumienia server-sent-events, podczas gdy sidecar zgłasza się jako niedostępny (SseStreamClient).

Właściwości

Ten typ nie niesie żadnych metadanych SPEC-*. Komunikat jest składany jako "Spectrum sidecar unavailable: {reason}", z opcjonalnym całkowitym code oraz powiązanym previous throwable.

Naprawa

Przechwyć to, gdy Spectrum jest opcjonalny, i cofnij się do przetwarzania natywnego PHP (płynna degradacja). Gdy Spectrum jest wymagany, potwierdź, że sidecar jest uruchomiony i osiągalny, a następnie ponownie uruchom wywołanie.

Zobacz także

• Indeks dokumentacji błędów
• Szyfrowanie i uprawnienia
• Indeks bazy wiedzy