Erreurs de l’Accelerator

Portée

Ces cinq exceptions font remonter les défaillances du sidecar d’accélérateur matériel optionnel Spectrum (Prism). Le sidecar est atteint via HTTP à travers NextPDF\Accelerator\SpectrumClient ; les réponses d’erreur portent un code SPEC-* lisible par machine issu d’une taxonomie canonique, et le client mappe ce code sur l’un des types d’exception ci-dessous.

Contrairement à la plupart des exceptions NextPDF, les exceptions de l’Accelerator n’implémentent pas getContext(). Elles étendent la RuntimeException de PHP et exposent leur état sous forme de propriétés publiques readonly typées. Distingue les domaines d’erreur en faisant correspondre le préfixe specCode (par exemple str_starts_with($e->specCode, 'SPEC-AUTH-')), pas en attrapant les sous-classes — la hiérarchie de sous-classes est interne et peut changer dans les versions mineures.

SpectrumApiException

SpectrumApiException est le type de base de toute réponse d’erreur du sidecar. Elle est levée directement pour tout code SPEC-* qui n’a pas de sous-classe plus spécifique, et c’est le type que tu attrapes pour traiter toutes les erreurs du sidecar d’un coup.

Quand elle est levée

• Le sidecar renvoie un corps d’erreur SPEC-* structuré. SpectrumResponseParser décode le corps et lève ce type pour tous les codes sauf SPEC-AUTH-* et SPEC-OOM-* (qui se mappent sur les sous-classes ci-dessous). Les correspondances documentées vers ce type de base incluent SPEC-INDEX-* (index de collection), SPEC-KMS-* (fournisseur de gestion de clés), SPEC-OCR-*, SPEC-MODEL-* et SPEC-BILLING-*.
• SPEC-IO-001 — le corps de la réponse n’est pas du JSON valide (httpStatus 502).
• SPEC-IO-002 — la version de l’API du sidecar est incompatible avec la minApiVersion configurée.
• SPEC-SEC-001 — une charge utile de document dépasse le budget de taille configuré (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — un chemin d’espace de travail échoue à la vérification de traversée (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — un identifiant de job est vide, trop long, ou contient des caractères hors de la liste d’autorisation d’ID opaque (SpectrumSecurityPolicy::validateJobId()).

Propriétés

Propriété	Type	Signification
specCode	string	Code d’erreur SPEC-* lisible par machine (par exemple SPEC-INDEX-003).
httpStatus	int	Statut HTTP que le sidecar a renvoyé ; vaut 500 par défaut. Aussi utilisé comme code de l’exception.
retryable	bool	Si l’opération peut être réessayée en toute sécurité. Vaut false par défaut.
traceId	?string	ID de trace de corrélation issu de l’en-tête de réponse X-Trace-Id, ou null.

Le message est composé sous la forme "[{specCode}] {message}". Trois prédicats d’assistance classent les domaines courants : isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) et isOcrError() (SPEC-OCR-*).

Rétablissement

1. Lis specCode pour identifier le domaine en échec ; branche sur son préfixe.
2. Honore retryable : ne réessaie que lorsqu’il vaut true, et jamais sur un code SPEC-SEC-* ou SPEC-IO-002, qui signalent des défauts de configuration ou de compatibilité.
3. Capture traceId dans tes journaux pour corréler l’échec avec les diagnostics côté sidecar dans un rapport de défaut.

Sous-classes de Spectrum

Les types suivants sont des sous-classes final de SpectrumApiException. Attrape SpectrumApiException (ou fais correspondre specCode) plutôt que celles-ci directement.

SpectrumAuthenticationException

Levée pour les codes SPEC-AUTH-*, indiquant un échec de licence, de jeton ou de liaison de déploiement. SpectrumResponseParser la lève chaque fois que le code de réponse commence par SPEC-AUTH-.

Les causes documentées incluent SPEC-AUTH-001 (signature Ed25519 de licence invalide), SPEC-AUTH-002 (licence expirée et hors de la période de grâce), SPEC-AUTH-003 (incohérence de slot de déploiement), SPEC-AUTH-004 (jeton Bearer JWT invalide), SPEC-AUTH-006 (licence dégradée, grâce expirée) et SPEC-AUTH-007 (fonctionnalité non incluse dans la licence achetée).

Elle porte les mêmes propriétés que le type de base, mais le constructeur fixe retryable à false et met httpStatus à 403 par défaut.

Rétablissement. Ces erreurs ne sont jamais réessayables sans intervention de l’opérateur. Renouvelle ou corrige la licence, rafraîchis le jeton Bearer, ou aligne le slot de déploiement, puis réexécute l’appel.

SpectrumResourceException

Levée pour les codes SPEC-OOM-* lorsque la mémoire GPU ou CPU est épuisée. SpectrumResponseParser la lève pour tout préfixe SPEC-OOM-, et le réglage DegradePolicy::FailFast la lève au lieu de rétrograder silencieusement vers un palier matériel inférieur.

Le constructeur fixe retryable à true et met httpStatus à 503 par défaut.

Rétablissement. Cette exception est réessayable. Mets le job en file d’attente et réessaie une fois que d’autres jobs se terminent et libèrent des ressources, ou relâche DegradePolicy vers AllowWithLog / WarnAndProceed si un palier rétrogradé est acceptable pour la charge de travail.

SpectrumProtocolException

Levée lorsqu’une réponse du sidecar s’analyse comme du JSON mais ne correspond pas à la forme de protocole attendue. Elle utilise toujours specCode SPEC-IO-003 et httpStatus 502, avec retryable fixé à false.

C’est distinct de SPEC-IO-001 (JSON invalide) : ici le JSON est bien formé mais structurellement erroné, ce qui indique typiquement un proxy ou une passerelle qui réécrit le corps, une version de sidecar incompatible, ou une réponse corrompue.

Rétablissement. Non réessayable — la forme de la réponse est déterministe pour une version de sidecar donnée. Vérifie la version du sidecar par rapport à la minApiVersion du client, inspecte tout proxy ou passerelle intermédiaire, puis redéploie un sidecar compatible.

SpectrumNotAvailableException

SpectrumNotAvailableException étend directement RuntimeException et ne fait pas partie de la hiérarchie SpectrumApiException. Elle signale que le sidecar est inaccessible ou a échoué à une vérification de santé, avant qu’un corps d’erreur SPEC-* n’ait pu être renvoyé.

Quand elle est levée

• Le disjoncteur est ouvert, ou toutes les tentatives de réessai sont épuisées (SpectrumClient).
• Une erreur de transport HTTP survient lors du contact avec le sidecar ; la ClientExceptionInterface PSR-18 sous-jacente est chaînée comme exception précédente.
• Un flux server-sent-events est demandé alors que le sidecar se déclare indisponible (SseStreamClient).

Propriétés

Ce type ne porte aucune métadonnée SPEC-*. Le message est composé sous la forme "Spectrum sidecar unavailable: {reason}", avec un code entier optionnel et un throwable previous chaîné.

Rétablissement

Attrape ceci lorsque Spectrum est optionnel et retombe sur le traitement natif PHP (dégradation gracieuse). Lorsque Spectrum est requis, confirme que le sidecar est en service et accessible, puis réexécute l’appel.

Voir aussi

• Index de la référence des erreurs
• Chiffrement et permissions
• Index de la base de connaissances