Accelerator-Fehler

Geltungsbereich

Diese fünf Exceptions fördern Fehler aus dem optionalen Spectrum-(Prism-) Hardware-Accelerator-Sidecar zutage. Der Sidecar wird über HTTP erreicht durch NextPDF\Accelerator\SpectrumClient; Fehlerantworten tragen einen maschinenlesbaren SPEC-*-Code aus einer kanonischen Taxonomie, und der Client ordnet diesen Code einem der unten stehenden Exception-Typen zu.

Anders als die meisten NextPDF-Exceptions implementieren die Accelerator-Exceptions nicht getContext(). Sie erweitern PHPs RuntimeException und legen ihren Zustand als typisierte, readonly öffentliche Eigenschaften offen. Unterscheiden Sie Fehlerdomänen durch Abgleich des specCode-Präfixes (zum Beispiel str_starts_with($e->specCode, 'SPEC-AUTH-')), nicht durch das Abfangen von Unterklassen — die Unterklassenhierarchie ist intern und kann sich in Minor-Versionen ändern.

SpectrumApiException

SpectrumApiException ist der Basistyp für jede Sidecar-Fehlerantwort. Es wird direkt für jeden SPEC-*-Code ausgelöst, der keine spezifischere Unterklasse hat, und es ist der Typ, den Sie abfangen, um alle Sidecar-Fehler auf einmal zu behandeln.

Wann es ausgelöst wird

• Der Sidecar gibt einen strukturierten SPEC-*-Fehlerkörper zurück. SpectrumResponseParser dekodiert den Körper und löst diesen Typ für alle Codes außer SPEC-AUTH-* und SPEC-OOM-* aus (die sich den unten stehenden Unterklassen zuordnen). Dokumentierte Zuordnungen zu diesem Basis- typ umfassen SPEC-INDEX-* (Collection-Index), SPEC-KMS-* (Schlüsselverwaltungs- Provider), SPEC-OCR-*, SPEC-MODEL-* und SPEC-BILLING-*.
• SPEC-IO-001 — der Antwortkörper ist kein gültiges JSON (httpStatus 502).
• SPEC-IO-002 — die Sidecar-API-Version ist inkompatibel mit der konfigurierten minApiVersion.
• SPEC-SEC-001 — eine Dokument-Payload überschreitet das konfigurierte Größenbudget (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — ein Workspace-Pfad besteht die Traversal-Prüfung nicht (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — ein Job-Bezeichner ist leer, zu lang oder enthält Zeichen außerhalb der Opaque-ID-Allowlist (SpectrumSecurityPolicy::validateJobId()).

Eigenschaften

Eigenschaft	Typ	Bedeutung
specCode	string	Maschinenlesbarer SPEC-*-Fehlercode (zum Beispiel SPEC-INDEX-003).
httpStatus	int	HTTP-Status, den der Sidecar zurückgab; standardmäßig 500. Wird auch als Exception-Code verwendet.
retryable	bool	Ob die Operation sicher wiederholt werden darf. Standardmäßig false.
traceId	?string	Korrelations-Trace-ID aus dem X-Trace-Id-Response-Header, oder null.

Die Meldung wird als "[{specCode}] {message}" zusammengesetzt. Drei Hilfsprädikate klassifizieren häufige Domänen: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) und isOcrError() (SPEC-OCR-*).

Behebung

1. Lesen Sie specCode, um die fehlschlagende Domäne zu identifizieren; verzweigen Sie auf ihr Präfix.
2. Berücksichtigen Sie retryable: Wiederholen Sie nur, wenn es true ist, und niemals bei einem SPEC-SEC-*- oder SPEC-IO-002-Code, die Konfigurations- oder Kompatibilitätsdefekte signalisieren.
3. Erfassen Sie traceId in Ihren Logs, um den Fehler mit sidecar-seitigen Diagnosen in einem Defektbericht zu korrelieren.

Spectrum-Unterklassen

Die folgenden Typen sind final-Unterklassen von SpectrumApiException. Fangen Sie SpectrumApiException ab (oder gleichen Sie auf specCode ab) statt diese direkt.

SpectrumAuthenticationException

Wird für SPEC-AUTH-*-Codes ausgelöst und zeigt einen Lizenz-, Token- oder Deployment- Bindungsfehler an. SpectrumResponseParser löst sie aus, wann immer der Response-Code mit SPEC-AUTH- beginnt.

Dokumentierte Ursachen umfassen SPEC-AUTH-001 (ungültige Lizenz-Ed25519-Signatur), SPEC-AUTH-002 (Lizenz abgelaufen und außerhalb der Grace-Period), SPEC-AUTH-003 (Deployment-Slot-Mismatch), SPEC-AUTH-004 (ungültiges JWT-Bearer-Token), SPEC-AUTH-006 (Lizenz degradiert, Grace abgelaufen) und SPEC-AUTH-007 (Feature nicht in der erworbenen Lizenz enthalten).

Es trägt dieselben Eigenschaften wie der Basistyp, aber der Konstruktor fixiert retryable auf false und setzt httpStatus standardmäßig auf 403.

Behebung. Diese Fehler sind ohne Betriebsintervention niemals wiederholbar. Erneuern oder korrigieren Sie die Lizenz, aktualisieren Sie das Bearer-Token, oder richten Sie den Deployment- Slot aus, und führen Sie den Aufruf dann erneut aus.

SpectrumResourceException

Wird für SPEC-OOM-*-Codes ausgelöst, wenn GPU- oder CPU-Speicher erschöpft ist. SpectrumResponseParser löst sie für jedes SPEC-OOM--Präfix aus, und die DegradePolicy::FailFast-Einstellung löst sie aus, statt stillschweigend auf ein niedrigeres Hardware-Tier herabzustufen.

Der Konstruktor fixiert retryable auf true und setzt httpStatus standardmäßig auf 503.

Behebung. Diese Exception ist wiederholbar. Stellen Sie den Job in die Queue und wiederholen Sie, nachdem andere Jobs abgeschlossen sind und Ressourcen freigegeben haben, oder lockern Sie DegradePolicy auf AllowWithLog / WarnAndProceed, wenn ein herabgestuftes Tier für die Arbeitslast akzeptabel ist.

SpectrumProtocolException

Wird ausgelöst, wenn eine Sidecar-Antwort als JSON parst, aber nicht der erwarteten Protokollform entspricht. Es verwendet immer specCode SPEC-IO-003 und httpStatus 502, mit retryable fixiert auf false.

Dies ist verschieden von SPEC-IO-001 (ungültiges JSON): hier ist das JSON wohlgeformt, aber strukturell falsch, was typischerweise auf einen Proxy oder ein Gateway hindeutet, das den Körper umschreibt, eine inkompatible Sidecar-Version oder eine beschädigte Antwort.

Behebung. Nicht wiederholbar — die Antwortform ist für eine gegebene Sidecar-Version deterministisch. Prüfen Sie die Sidecar-Version gegen die minApiVersion des Clients, inspizieren Sie jeden zwischengeschalteten Proxy oder jedes Gateway, und stellen Sie dann einen kompatiblen Sidecar erneut bereit.

SpectrumNotAvailableException

SpectrumNotAvailableException erweitert RuntimeException direkt und ist nicht Teil der SpectrumApiException-Hierarchie. Es signalisiert, dass der Sidecar unerreichbar ist oder einen Health-Check nicht bestanden hat, bevor ein SPEC-*-Fehlerkörper zurückgegeben werden konnte.

Wann es ausgelöst wird

• Der Circuit Breaker ist offen, oder alle Wiederholungsversuche sind erschöpft (SpectrumClient).
• Ein HTTP-Transportfehler tritt beim Kontaktieren des Sidecar auf; das zugrunde liegende PSR-18-ClientExceptionInterface wird als vorherige Exception verkettet.
• Ein Server-Sent-Events-Stream wird angefordert, während der Sidecar sich selbst als nicht verfügbar meldet (SseStreamClient).

Eigenschaften

Dieser Typ trägt keine SPEC-*-Metadaten. Die Meldung wird als "Spectrum sidecar unavailable: {reason}" zusammengesetzt, mit einem optionalen Integer-code und einem verketteten previous-Throwable.

Behebung

Fangen Sie dies ab, wenn Spectrum optional ist, und fallen Sie auf PHP-native Verarbeitung zurück (graceful degradation). Wenn Spectrum erforderlich ist, bestätigen Sie, dass der Sidecar läuft und erreichbar ist, und führen Sie den Aufruf dann erneut aus.

Siehe auch

• Index der Fehlerreferenz
• Verschlüsselung und Berechtigungen
• Index der Wissensdatenbank