Errores del acelerador

Alcance

Estas cinco excepciones afloran los fallos del sidecar opcional del acelerador hardware Spectrum (Prism). Se accede al sidecar por HTTP a través de NextPDF\Accelerator\SpectrumClient; las respuestas de error transportan un código SPEC-* legible por máquina de una taxonomía canónica, y el cliente asigna ese código a uno de los tipos de excepción de abajo.

A diferencia de la mayoría de las excepciones de NextPDF, las excepciones del acelerador no implementan getContext(). Extienden RuntimeException de PHP y exponen su estado como propiedades públicas tipadas de readonly. Discriminar los dominios de error comparando el prefijo de specCode (por ejemplo str_starts_with($e->specCode, 'SPEC-AUTH-')), no capturando subclases: la jerarquía de subclases es interna y puede cambiar en versiones menores.

SpectrumApiException

SpectrumApiException es el tipo base de toda respuesta de error del sidecar. Se lanza directamente para cualquier código SPEC-* que no tenga una subclase más específica, y es el tipo que se captura para manejar de una vez todos los errores del sidecar.

Cuándo se lanza

• El sidecar devuelve un cuerpo de error SPEC-* estructurado. SpectrumResponseParser decodifica el cuerpo y lanza este tipo para todos los códigos excepto SPEC-AUTH-* y SPEC-OOM-* (que se asignan a las subclases de abajo). Las asignaciones documentadas a este tipo base incluyen SPEC-INDEX-* (índice de colección), SPEC-KMS-* (proveedor de gestión de claves), SPEC-OCR-*, SPEC-MODEL-* y SPEC-BILLING-*.
• SPEC-IO-001: el cuerpo de la respuesta no es JSON válido (httpStatus 502).
• SPEC-IO-002: la versión de la API del sidecar es incompatible con el minApiVersion configurado.
• SPEC-SEC-001: la carga útil de un documento supera el presupuesto de tamaño configurado (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003: una ruta de espacio de trabajo no supera la comprobación de traspaso (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004: un identificador de trabajo está vacío, es demasiado largo o contiene caracteres fuera de la lista de permitidos del ID opaco (SpectrumSecurityPolicy::validateJobId()).

Propiedades

Propiedad	Tipo	Significado
specCode	string	Código de error SPEC-* legible por máquina (por ejemplo SPEC-INDEX-003).
httpStatus	int	Estado HTTP que devolvió el sidecar; el valor predeterminado es 500. Se usa también como código de la excepción.
retryable	bool	Si la operación puede reintentarse de forma segura. El valor predeterminado es false.
traceId	?string	ID de traza de correlación de la cabecera de respuesta X-Trace-Id, o null.

El mensaje se compone como "[{specCode}] {message}". Tres predicados auxiliares clasifican dominios comunes: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) e isOcrError() (SPEC-OCR-*).

Recuperación

1. Leer specCode para identificar el dominio que falla; ramificar según su prefijo.
2. Respetar retryable: reintentar solo cuando es true, y nunca con un código SPEC-SEC-* o SPEC-IO-002, que señalan defectos de configuración o de compatibilidad.
3. Capturar traceId en los registros para correlacionar el fallo con el diagnóstico del lado del sidecar en un informe de defectos.

Subclases de Spectrum

Los siguientes tipos son subclases final de SpectrumApiException. Conviene capturar SpectrumApiException (o comparar specCode) en lugar de estas directamente.

SpectrumAuthenticationException

Se lanza para los códigos SPEC-AUTH-*, que indican un fallo de licencia, de token o de vínculo de despliegue. SpectrumResponseParser la genera siempre que el código de respuesta empieza por SPEC-AUTH-.

Las causas documentadas incluyen SPEC-AUTH-001 (firma Ed25519 de licencia no válida), SPEC-AUTH-002 (licencia caducada y fuera del periodo de gracia), SPEC-AUTH-003 (desajuste de la ranura de despliegue), SPEC-AUTH-004 (token Bearer JWT no válido), SPEC-AUTH-006 (licencia degradada, gracia caducada) y SPEC-AUTH-007 (funcionalidad no incluida en la licencia adquirida).

Transporta las mismas propiedades que el tipo base, pero el constructor fija retryable en false y establece httpStatus en 403 por defecto.

Recuperación. Estos errores nunca son reintentables sin intervención del operador. Renovar o corregir la licencia, actualizar el token Bearer o alinear la ranura de despliegue, y luego volver a ejecutar la llamada.

SpectrumResourceException

Se lanza para los códigos SPEC-OOM-* cuando se agota la memoria de la GPU o de la CPU. SpectrumResponseParser la genera para cualquier prefijo SPEC-OOM-, y la configuración DegradePolicy::FailFast la genera en lugar de degradar de forma silenciosa a un nivel de hardware inferior.

El constructor fija retryable en true y establece httpStatus en 503 por defecto.

Recuperación. Esta excepción es reintentable. Encolar el trabajo y reintentar después de que otros trabajos finalicen y liberen recursos, o relajar DegradePolicy a AllowWithLog / WarnAndProceed si un nivel degradado es aceptable para la carga de trabajo.

SpectrumProtocolException

Se lanza cuando una respuesta del sidecar se analiza como JSON pero no coincide con la forma de protocolo esperada. Siempre usa el specCode SPEC-IO-003 y el httpStatus 502, con retryable fijado en false.

Esto es distinto de SPEC-IO-001 (JSON no válido): aquí el JSON está bien formado pero es estructuralmente incorrecto, lo que normalmente indica un proxy o una pasarela que reescribe el cuerpo, una versión incompatible del sidecar o una respuesta dañada.

Recuperación. No reintentable: la forma de la respuesta es determinista para una versión dada del sidecar. Verificar la versión del sidecar contra el minApiVersion del cliente, inspeccionar cualquier proxy o pasarela intermedios y luego volver a desplegar un sidecar compatible.

SpectrumNotAvailableException

SpectrumNotAvailableException extiende directamente RuntimeException y no forma parte de la jerarquía de SpectrumApiException. Señala que el sidecar es inalcanzable o no superó una comprobación de estado, antes de que pudiera devolverse cualquier cuerpo de error SPEC-*.

Cuándo se lanza

• El disyuntor está abierto, o se agotaron todos los intentos de reintento (SpectrumClient).
• Se produce un error de transporte HTTP al contactar con el sidecar; la ClientExceptionInterface subyacente de PSR-18 se encadena como excepción previa.
• Se solicita un flujo de eventos enviados por el servidor mientras el sidecar se declara a sí mismo no disponible (SseStreamClient).

Propiedades

Este tipo no transporta metadatos SPEC-*. El mensaje se compone como "Spectrum sidecar unavailable: {reason}", con un code entero opcional y una previous lanzable encadenada.

Recuperación

Capturar esto cuando Spectrum es opcional y recurrir al procesamiento nativo de PHP (degradación elegante). Cuando Spectrum es obligatorio, confirmar que el sidecar está activo y es accesible, y luego volver a ejecutar la llamada.

Véase también

• Índice de la referencia de errores
• Cifrado y permisos
• Índice de la base de conocimientos