Erros do Accelerator

Escopo

Estas cinco exceções expõem falhas do sidecar de acelerador de hardware Spectrum (Prism) opcional. O sidecar é alcançado por HTTP por meio de NextPDF\Accelerator\SpectrumClient; as respostas de erro carregam um código SPEC-* legível por máquina de uma taxonomia canônica, e o cliente mapeia esse código para um dos tipos de exceção abaixo.

Ao contrário da maioria das exceções do NextPDF, as exceções do Accelerator não implementam getContext(). Elas estendem a RuntimeException do PHP e expõem seu estado como propriedades públicas tipadas e readonly. Discrimine domínios de erro fazendo correspondência do prefixo specCode (por exemplo str_starts_with($e->specCode, 'SPEC-AUTH-')), não capturando subclasses — a hierarquia de subclasses é interna e pode mudar em versões menores.

SpectrumApiException

SpectrumApiException é o tipo base para toda resposta de erro do sidecar. Ela é gerada diretamente para qualquer código SPEC-* que não tenha uma subclasse mais específica, e é o tipo que você captura para tratar todos os erros do sidecar de uma vez.

Quando é gerada

• O sidecar retorna um corpo de erro estruturado SPEC-*. SpectrumResponseParser decodifica o corpo e gera este tipo para todos os códigos, exceto SPEC-AUTH-* e SPEC-OOM-* (que mapeiam para as subclasses abaixo). Os mapeamentos documentados para este tipo base incluem SPEC-INDEX-* (índice de coleção), SPEC-KMS-* (provedor de gerenciamento de chaves), SPEC-OCR-*, SPEC-MODEL-* e SPEC-BILLING-*.
• SPEC-IO-001 — o corpo da resposta não é JSON válido (httpStatus 502).
• SPEC-IO-002 — a versão da API do sidecar é incompatível com a minApiVersion configurada.
• SPEC-SEC-001 — um payload de documento excede o orçamento de tamanho configurado (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — um caminho de workspace falha na verificação de traversal (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — um identificador de job está vazio, é longo demais ou contém caracteres fora da allowlist de IDs opacos (SpectrumSecurityPolicy::validateJobId()).

Propriedades

Propriedade	Tipo	Significado
specCode	string	Código de erro SPEC-* legível por máquina (por exemplo SPEC-INDEX-003).
httpStatus	int	Status HTTP que o sidecar retornou; o padrão é 500. Também usado como o código da exceção.
retryable	bool	Se a operação pode ser repetida com segurança. O padrão é false.
traceId	?string	ID de trace de correlação do header de resposta X-Trace-Id, ou null.

A mensagem é composta como "[{specCode}] {message}". Três predicados auxiliares classificam domínios comuns: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) e isOcrError() (SPEC-OCR-*).

Recuperação

1. Leia specCode para identificar o domínio que está falhando; ramifique por seu prefixo.
2. Respeite retryable: tente novamente apenas quando for true, e nunca em um código SPEC-SEC-* ou SPEC-IO-002, que sinalizam defeitos de configuração ou de compatibilidade.
3. Capture traceId em seus logs para correlacionar a falha com os diagnósticos do lado do sidecar em um relatório de defeito.

Subclasses de Spectrum

Os tipos a seguir são subclasses final de SpectrumApiException. Capture SpectrumApiException (ou faça correspondência por specCode) em vez destas diretamente.

SpectrumAuthenticationException

Gerada para códigos SPEC-AUTH-*, indicando uma falha de vinculação de licença, token ou implantação. SpectrumResponseParser a gera sempre que o código de resposta começa com SPEC-AUTH-.

As causas documentadas incluem SPEC-AUTH-001 (assinatura Ed25519 de licença inválida), SPEC-AUTH-002 (licença expirada e fora do período de carência), SPEC-AUTH-003 (incompatibilidade de slot de implantação), SPEC-AUTH-004 (token JWT Bearer inválido), SPEC-AUTH-006 (licença degradada, carência expirada) e SPEC-AUTH-007 (recurso não incluído na licença adquirida).

Ela carrega as mesmas propriedades que o tipo base, mas o construtor fixa retryable em false e define httpStatus como 403 por padrão.

Recuperação. Esses erros nunca podem ser repetidos sem intervenção do operador. Renove ou corrija a licença, atualize o token Bearer, ou alinhe o slot de implantação, então execute a chamada novamente.

SpectrumResourceException

Gerada para códigos SPEC-OOM-* quando a memória de GPU ou CPU é esgotada. SpectrumResponseParser a gera para qualquer prefixo SPEC-OOM-, e a configuração DegradePolicy::FailFast a gera em vez de fazer downgrade silencioso para um tier de hardware inferior.

O construtor fixa retryable em true e define httpStatus como 503 por padrão.

Recuperação. Esta exceção pode ser repetida. Coloque o job na fila e tente novamente após outros jobs concluírem e liberarem recursos, ou relaxe DegradePolicy para AllowWithLog / WarnAndProceed se um tier rebaixado for aceitável para a carga de trabalho.

SpectrumProtocolException

Gerada quando uma resposta do sidecar é parseada como JSON, mas não corresponde ao formato de protocolo esperado. Ela sempre usa o specCode SPEC-IO-003 e o httpStatus 502, com retryable fixado em false.

Isto é distinto de SPEC-IO-001 (JSON inválido): aqui o JSON é bem formado, mas estruturalmente errado, o que normalmente indica um proxy ou gateway reescrevendo o corpo, uma versão de sidecar incompatível ou uma resposta corrompida.

Recuperação. Não pode ser repetida — o formato da resposta é determinístico para uma dada versão de sidecar. Verifique a versão do sidecar contra a minApiVersion do cliente, inspecione qualquer proxy ou gateway intermediário, então reimplante um sidecar compatível.

SpectrumNotAvailableException

SpectrumNotAvailableException estende RuntimeException diretamente e não faz parte da hierarquia de SpectrumApiException. Ela sinaliza que o sidecar está inacessível ou falhou em uma verificação de saúde, antes que qualquer corpo de erro SPEC-* pudesse ser retornado.

Quando é gerada

• O circuit breaker está aberto, ou todas as tentativas de retry estão esgotadas (SpectrumClient).
• Um erro de transporte HTTP ocorre ao contatar o sidecar; a ClientExceptionInterface do PSR-18 subjacente é encadeada como a exceção anterior.
• Um stream de server-sent-events é solicitado enquanto o sidecar se relata indisponível (SseStreamClient).

Propriedades

Este tipo não carrega metadados SPEC-*. A mensagem é composta como "Spectrum sidecar unavailable: {reason}", com um code inteiro opcional e um throwable previous encadeado.

Recuperação

Capture isto quando o Spectrum for opcional e recorra ao processamento nativo em PHP (degradação graciosa). Quando o Spectrum for obrigatório, confirme que o sidecar está no ar e acessível, então execute a chamada novamente.

Veja também

• Índice de referência de erros
• Criptografia e permissões
• Índice da base de conhecimento