Errori dell'Accelerator

Ambito

Queste cinque eccezioni fanno emergere i guasti del sidecar di accelerazione hardware Spectrum (Prism) opzionale. Il sidecar è raggiunto via HTTP tramite NextPDF\Accelerator\SpectrumClient; le risposte di errore trasportano un codice SPEC-* leggibile a macchina da una tassonomia canonica, e il client mappa quel codice su uno dei tipi di eccezione seguenti.

A differenza della maggior parte delle eccezioni NextPDF, le eccezioni dell’Accelerator non implementano getContext(). Estendono la RuntimeException di PHP ed espongono il proprio stato come proprietà pubbliche tipizzate e readonly. Discriminare i domini di errore confrontando il prefisso di specCode (ad esempio str_starts_with($e->specCode, 'SPEC-AUTH-')), non intercettando le sottoclassi — la gerarchia delle sottoclassi è interna e può cambiare nelle versioni minor.

SpectrumApiException

SpectrumApiException è il tipo base per ogni risposta di errore del sidecar. Viene sollevata direttamente per qualsiasi codice SPEC-* privo di una sottoclasse più specifica, ed è il tipo da intercettare per gestire in una sola volta tutti gli errori del sidecar.

Quando viene sollevata

• Il sidecar restituisce un corpo di errore strutturato SPEC-*. SpectrumResponseParser decodifica il corpo e solleva questo tipo per tutti i codici tranne SPEC-AUTH-* e SPEC-OOM-* (che mappano alle sottoclassi sotto). Le mappature documentate verso questo tipo base includono SPEC-INDEX-* (indice di collezione), SPEC-KMS-* (provider di gestione delle chiavi), SPEC-OCR-*, SPEC-MODEL-* e SPEC-BILLING-*.
• SPEC-IO-001 — il corpo della risposta non è JSON valido (httpStatus 502).
• SPEC-IO-002 — la versione dell’API del sidecar è incompatibile con il minApiVersion configurato.
• SPEC-SEC-001 — un payload di documento supera il budget di dimensione configurato (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — un percorso di workspace fallisce il controllo di traversal (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — un identificatore di job è vuoto, troppo lungo o contiene caratteri fuori dalla allowlist degli ID opachi (SpectrumSecurityPolicy::validateJobId()).

Proprietà

Proprietà	Tipo	Significato
specCode	string	Codice di errore SPEC-* leggibile a macchina (ad esempio SPEC-INDEX-003).
httpStatus	int	Stato HTTP restituito dal sidecar; valore predefinito 500. Usato anche come codice dell’eccezione.
retryable	bool	Se l’operazione può essere ritentata in sicurezza. Valore predefinito false.
traceId	?string	Trace ID di correlazione dall’header di risposta X-Trace-Id, oppure null.

Il messaggio è composto come "[{specCode}] {message}". Tre predicati helper classificano i domini comuni: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) e isOcrError() (SPEC-OCR-*).

Recupero

1. Leggere specCode per individuare il dominio fallito; diramare sul suo prefisso.
2. Onorare retryable: riprovare solo quando è true, e mai su un codice SPEC-SEC-* o SPEC-IO-002, che segnalano difetti di configurazione o di compatibilità.
3. Acquisire traceId nei propri log per correlare il guasto con le diagnosi lato sidecar in una segnalazione di difetto.

Sottoclassi Spectrum

I tipi seguenti sono sottoclassi final di SpectrumApiException. Intercettare SpectrumApiException (o confrontare su specCode) anziché queste direttamente.

SpectrumAuthenticationException

Sollevata per i codici SPEC-AUTH-*, che indicano un guasto di licenza, token o binding del deployment. SpectrumResponseParser la solleva ogni volta che il codice della risposta inizia con SPEC-AUTH-.

Le cause documentate includono SPEC-AUTH-001 (firma Ed25519 della licenza non valida), SPEC-AUTH-002 (licenza scaduta e fuori dal periodo di grazia), SPEC-AUTH-003 (mancata corrispondenza dello slot di deployment), SPEC-AUTH-004 (token JWT Bearer non valido), SPEC-AUTH-006 (licenza degradata, grazia scaduta) e SPEC-AUTH-007 (funzionalità non inclusa nella licenza acquistata).

Trasporta le stesse proprietà del tipo base, ma il costruttore fissa retryable a false e imposta httpStatus predefinito a 403.

Recupero. Questi errori non sono mai ritentabili senza l’intervento di un operatore. Rinnovare o correggere la licenza, aggiornare il token Bearer, oppure allineare lo slot di deployment, quindi rieseguire la chiamata.

SpectrumResourceException

Sollevata per i codici SPEC-OOM-* quando la memoria GPU o CPU è esaurita. SpectrumResponseParser la solleva per qualsiasi prefisso SPEC-OOM-, e l’impostazione DegradePolicy::FailFast la solleva anziché degradare silenziosamente a un tier hardware inferiore.

Il costruttore fissa retryable a true e imposta httpStatus predefinito a 503.

Recupero. Questa eccezione è ritentabile. Accodare il job e riprovare dopo che altri job sono completati e hanno liberato risorse, oppure allentare DegradePolicy a AllowWithLog / WarnAndProceed se un tier degradato è accettabile per il carico di lavoro.

SpectrumProtocolException

Sollevata quando una risposta del sidecar si analizza come JSON ma non corrisponde alla forma di protocollo attesa. Usa sempre specCode SPEC-IO-003 e httpStatus 502, con retryable fissato a false.

Questo è distinto da SPEC-IO-001 (JSON non valido): qui il JSON è ben formato ma strutturalmente errato, il che indica tipicamente un proxy o un gateway che riscrive il corpo, una versione incompatibile del sidecar o una risposta corrotta.

Recupero. Non ritentabile — la forma della risposta è deterministica per una data versione del sidecar. Verificare la versione del sidecar rispetto al minApiVersion del client, ispezionare qualsiasi proxy o gateway intermedio, quindi ridistribuire un sidecar compatibile.

SpectrumNotAvailableException

SpectrumNotAvailableException estende direttamente RuntimeException e non fa parte della gerarchia di SpectrumApiException. Segnala che il sidecar è irraggiungibile o ha fallito un health check, prima che potesse essere restituito un corpo di errore SPEC-*.

Quando viene sollevata

• Il circuit breaker è aperto, oppure tutti i tentativi di retry sono esauriti (SpectrumClient).
• Si verifica un errore di trasporto HTTP mentre si contatta il sidecar; la ClientExceptionInterface PSR-18 sottostante è concatenata come eccezione precedente.
• Viene richiesto uno stream di server-sent-events mentre il sidecar si dichiara non disponibile (SseStreamClient).

Proprietà

Questo tipo non trasporta metadati SPEC-*. Il messaggio è composto come "Spectrum sidecar unavailable: {reason}", con un code intero opzionale e un throwable previous concatenato.

Recupero

Intercettare questa quando Spectrum è opzionale e ripiegare sull’elaborazione nativa in PHP (degradazione controllata). Quando Spectrum è richiesto, confermare che il sidecar sia attivo e raggiungibile, quindi rieseguire la chiamata.

Vedere anche

• Indice del riferimento degli errori
• Cifratura e permessi
• Indice della knowledge base