Accelerator-fouten

Reikwijdte

Deze vijf uitzonderingen brengen storingen aan de oppervlakte vanuit de optionele Spectrum (Prism)- hardware-accelerator-sidecar. De sidecar wordt over HTTP bereikt via NextPDF\Accelerator\SpectrumClient; error-antwoorden dragen een machine-leesbare SPEC-*-code uit een canonieke taxonomie, en de client mapt die code naar een van de onderstaande uitzonderingstypes.

Anders dan de meeste NextPDF-uitzonderingen implementeren de Accelerator-uitzonderingen geen getContext(). Zij breiden PHP’s RuntimeException uit en stellen hun staat beschikbaar als getypeerde, readonly publieke properties. Discrimineer foutdomeinen door de specCode-prefix te matchen (bijvoorbeeld str_starts_with($e->specCode, 'SPEC-AUTH-')), niet door subklassen op te vangen — de subklasse-hiërarchie is intern en kan veranderen in minor versions.

SpectrumApiException

SpectrumApiException is het basistype voor elk sidecar-error-antwoord. Hij wordt rechtstreeks opgeworpen voor elke SPEC-*-code die geen specifiekere subklasse heeft, en hij is het type dat je opvangt om alle sidecar-fouten in één keer af te handelen.

Wanneer hij wordt opgeworpen

• De sidecar geeft een gestructureerde SPEC-*-error-body terug. SpectrumResponseParser decodeert de body en werpt dit type op voor alle codes behalve SPEC-AUTH-* en SPEC-OOM-* (die mappen naar de onderstaande subklassen). Gedocumenteerde mappings naar dit basis- type omvatten SPEC-INDEX-* (collection index), SPEC-KMS-* (key-management- provider), SPEC-OCR-*, SPEC-MODEL-*, en SPEC-BILLING-*.
• SPEC-IO-001 — de response-body is geen geldige JSON (httpStatus 502).
• SPEC-IO-002 — de sidecar-API-versie is incompatibel met de geconfigureerde minApiVersion.
• SPEC-SEC-001 — een document-payload overschrijdt het geconfigureerde grootte-budget (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — een workspace-pad faalt de traversal-controle (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — een job-identifier is leeg, te lang, of bevat tekens buiten de opaque-ID-allowlist (SpectrumSecurityPolicy::validateJobId()).

Eigenschappen

Property	Type	Betekenis
specCode	string	Machine-leesbare SPEC-*-error-code (bijvoorbeeld SPEC-INDEX-003).
httpStatus	int	HTTP-status die de sidecar teruggaf; valt standaard terug op 500. Ook gebruikt als de exception-code.
retryable	bool	Of de bewerking veilig opnieuw mag worden geprobeerd. Valt standaard terug op false.
traceId	?string	Correlatie-trace-ID uit de X-Trace-Id-response-header, of null.

Het bericht wordt samengesteld als "[{specCode}] {message}". Drie helper-predicaten classificeren veelvoorkomende domeinen: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*), en isOcrError() (SPEC-OCR-*).

Herstel

1. Lees specCode om het falende domein te identificeren; vertak op zijn prefix.
2. Honoreer retryable: probeer alleen opnieuw wanneer hij true is, en nooit op een SPEC-SEC-*- of SPEC-IO-002-code, die op configuratie- of compatibiliteitsdefecten duiden.
3. Leg traceId vast in je logs om de storing te correleren met sidecar-zijde- diagnostiek in een defect-rapport.

Spectrum-subklassen

De volgende types zijn final subklassen van SpectrumApiException. Vang SpectrumApiException op (of match op specCode) in plaats van deze rechtstreeks.

SpectrumAuthenticationException

Opgeworpen voor SPEC-AUTH-*-codes, die op een license-, token- of deployment- binding-storing duiden. SpectrumResponseParser werpt hem op telkens wanneer de response-code begint met SPEC-AUTH-.

Gedocumenteerde oorzaken omvatten SPEC-AUTH-001 (ongeldige license-Ed25519-handtekening), SPEC-AUTH-002 (license verlopen en buiten de grace period), SPEC-AUTH-003 (deployment-slot-mismatch), SPEC-AUTH-004 (ongeldig JWT-Bearer-token), SPEC-AUTH-006 (license gedegradeerd, grace verlopen), en SPEC-AUTH-007 (feature niet inbegrepen in de gekochte license).

Hij draagt dezelfde properties als het basistype, maar de constructor pint retryable op false en laat httpStatus standaard terugvallen op 403.

Herstel. Deze fouten zijn nooit retrybaar zonder operatorinterventie. Vernieuw of corrigeer de license, ververs het Bearer-token, of stem de deployment- slot af, en voer dan de aanroep opnieuw uit.

SpectrumResourceException

Opgeworpen voor SPEC-OOM-*-codes wanneer GPU- of CPU-geheugen is uitgeput. SpectrumResponseParser werpt hem op voor elke SPEC-OOM--prefix, en de DegradePolicy::FailFast-instelling werpt hem op in plaats van stilletjes te downgraden naar een lagere hardware-tier.

De constructor pint retryable op true en laat httpStatus standaard terugvallen op 503.

Herstel. Deze uitzondering is retrybaar. Plaats de job in de wachtrij en probeer opnieuw nadat andere jobs voltooid zijn en resources hebben vrijgemaakt, of versoepel DegradePolicy naar AllowWithLog / WarnAndProceed als een gedowngrade tier acceptabel is voor de workload.

SpectrumProtocolException

Opgeworpen wanneer een sidecar-antwoord als JSON parset maar niet overeenkomt met de verwachte protocol-vorm. Hij gebruikt altijd specCode SPEC-IO-003 en httpStatus 502, met retryable gepind op false.

Dit is te onderscheiden van SPEC-IO-001 (ongeldige JSON): hier is de JSON welgevormd maar structureel verkeerd, wat doorgaans duidt op een proxy of gateway die de body herschrijft, een incompatibele sidecar-versie, of een beschadigd antwoord.

Herstel. Niet retrybaar — de response-vorm is deterministisch voor een gegeven sidecar-versie. Verifieer de sidecar-versie tegen de minApiVersion van de client, inspecteer eventuele tussenliggende proxy of gateway, en herdeploy dan een compatibele sidecar.

SpectrumNotAvailableException

SpectrumNotAvailableException breidt RuntimeException rechtstreeks uit en is geen onderdeel van de SpectrumApiException-hiërarchie. Hij signaleert dat de sidecar onbereikbaar is of een health check faalde, voordat enige SPEC-*-error-body kon worden teruggegeven.

Wanneer hij wordt opgeworpen

• De circuit breaker is open, of alle retry-pogingen zijn uitgeput (SpectrumClient).
• Er treedt een HTTP-transportfout op tijdens het contacteren van de sidecar; de onderliggende PSR-18-ClientExceptionInterface wordt geketend als de vorige uitzondering.
• Een server-sent-events-stream wordt opgevraagd terwijl de sidecar zichzelf als niet beschikbaar rapporteert (SseStreamClient).

Eigenschappen

Dit type draagt geen SPEC-*-metadata. Het bericht wordt samengesteld als "Spectrum sidecar unavailable: {reason}", met een optionele integer code en een geketende previous throwable.

Herstel

Vang dit op wanneer Spectrum optioneel is en val terug op PHP-native verwerking (graceful degradation). Wanneer Spectrum vereist is, bevestig dat de sidecar up en bereikbaar is, en voer dan de aanroep opnieuw uit.

Zie ook

• Foutreferentie-index
• Versleuteling en machtigingen
• Kennisbank-index