Kesalahan Accelerator

Cakupan

Kelima eksepsi ini memunculkan kegagalan dari sidecar accelerator-perangkat-keras Spectrum (Prism) opsional. Sidecar dijangkau melalui HTTP via NextPDF\Accelerator\SpectrumClient; respons kesalahan membawa kode SPEC-* yang dapat-dibaca-mesin dari taksonomi kanonis, dan klien memetakan kode tersebut ke salah satu tipe eksepsi di bawah.

Tidak seperti sebagian besar eksepsi NextPDF, eksepsi Accelerator tidak mengimplementasikan getContext(). Eksepsi ini memperluas RuntimeException PHP dan memaparkan statusnya sebagai properti publik readonly bertipe. Diskriminasi domain kesalahan dengan mencocokkan prefiks specCode (misalnya str_starts_with($e->specCode, 'SPEC-AUTH-')), bukan dengan menangkap subkelas — hierarki subkelas bersifat internal dan dapat berubah dalam versi minor.

SpectrumApiException

SpectrumApiException adalah tipe basis untuk setiap respons kesalahan sidecar. Eksepsi ini dilemparkan secara langsung untuk setiap kode SPEC-* yang tidak memiliki subkelas yang lebih spesifik, dan ia adalah tipe yang Anda tangkap untuk menangani semua kesalahan sidecar sekaligus.

Kapan dilemparkan

• Sidecar mengembalikan badan kesalahan SPEC-* terstruktur. SpectrumResponseParser mendekode badan tersebut dan melemparkan tipe ini untuk semua kode kecuali SPEC-AUTH-* dan SPEC-OOM-* (yang memetakan ke subkelas di bawah). Pemetaan terdokumentasi ke tipe basis ini mencakup SPEC-INDEX-* (collection index), SPEC-KMS-* (penyedia key-management), SPEC-OCR-*, SPEC-MODEL-*, dan SPEC-BILLING-*.
• SPEC-IO-001 — badan respons bukan JSON yang valid (httpStatus 502).
• SPEC-IO-002 — versi API sidecar tidak kompatibel dengan minApiVersion yang dikonfigurasi.
• SPEC-SEC-001 — sebuah payload dokumen melampaui anggaran ukuran yang dikonfigurasi (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — sebuah jalur workspace gagal pemeriksaan penelusuran (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — sebuah pengenal job kosong, terlalu panjang, atau berisi karakter di luar allowlist opaque-ID (SpectrumSecurityPolicy::validateJobId()).

Properti

Properti	Tipe	Makna
specCode	string	Kode kesalahan SPEC-* yang dapat-dibaca-mesin (misalnya SPEC-INDEX-003).
httpStatus	int	Status HTTP yang dikembalikan sidecar; default ke 500. Juga digunakan sebagai kode eksepsi.
retryable	bool	Apakah operasi dapat dicoba ulang dengan aman. Default ke false.
traceId	?string	Trace ID korelasi dari header respons X-Trace-Id, atau null.

Pesan disusun sebagai "[{specCode}] {message}". Tiga predikat helper mengklasifikasikan domain umum: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*), dan isOcrError() (SPEC-OCR-*).

Pemulihan

1. Baca specCode untuk mengidentifikasi domain yang gagal; bercabanglah pada prefiksnya.
2. Hormati retryable: coba ulang hanya ketika true, dan jangan pernah pada kode SPEC-SEC-* atau SPEC-IO-002, yang menandakan cacat konfigurasi atau kompatibilitas.
3. Tangkap traceId dalam log Anda untuk mengorelasikan kegagalan dengan diagnostik sisi-sidecar dalam laporan cacat.

Subkelas Spectrum

Tipe-tipe berikut adalah subkelas final dari SpectrumApiException. Tangkap SpectrumApiException (atau cocokkan pada specCode) alih-alih tipe-tipe ini secara langsung.

SpectrumAuthenticationException

Dilemparkan untuk kode SPEC-AUTH-*, menunjukkan kegagalan pengikatan lisensi, token, atau deployment. SpectrumResponseParser memunculkannya setiap kali kode respons dimulai dengan SPEC-AUTH-.

Penyebab terdokumentasi mencakup SPEC-AUTH-001 (tanda tangan Ed25519 lisensi tidak valid), SPEC-AUTH-002 (lisensi kedaluwarsa dan di luar periode tenggang), SPEC-AUTH-003 (ketidakcocokan deployment slot), SPEC-AUTH-004 (token JWT Bearer tidak valid), SPEC-AUTH-006 (lisensi terdegradasi, tenggang kedaluwarsa), dan SPEC-AUTH-007 (fitur tidak termasuk dalam lisensi yang dibeli).

Eksepsi ini membawa properti yang sama dengan tipe basis, tetapi konstruktornya menetapkan retryable ke false dan default httpStatus ke 403.

Pemulihan. Kesalahan-kesalahan ini tidak pernah dapat dicoba ulang tanpa intervensi operator. Perbarui atau perbaiki lisensi, segarkan token Bearer, atau selaraskan deployment slot, lalu jalankan ulang panggilan tersebut.

SpectrumResourceException

Dilemparkan untuk kode SPEC-OOM-* ketika memori GPU atau CPU habis. SpectrumResponseParser memunculkannya untuk setiap prefiks SPEC-OOM-, dan setelan DegradePolicy::FailFast memunculkannya alih-alih secara senyap menurunkan ke tier perangkat-keras yang lebih rendah.

Konstruktor menetapkan retryable ke true dan default httpStatus ke 503.

Pemulihan. Eksepsi ini dapat dicoba ulang. Antrekan job dan coba ulang setelah job lain selesai dan membebaskan sumber daya, atau longgarkan DegradePolicy ke AllowWithLog / WarnAndProceed jika tier yang diturunkan dapat diterima untuk beban kerja tersebut.

SpectrumProtocolException

Dilemparkan ketika sebuah respons sidecar terurai sebagai JSON tetapi tidak cocok dengan bentuk protokol yang diharapkan. Eksepsi ini selalu menggunakan specCode SPEC-IO-003 dan httpStatus 502, dengan retryable ditetapkan ke false.

Ini berbeda dari SPEC-IO-001 (JSON tidak valid): di sini JSON terbentuk-baik tetapi salah secara struktural, yang biasanya menunjukkan proxy atau gateway yang menulis ulang badan, versi sidecar yang tidak kompatibel, atau respons yang rusak.

Pemulihan. Tidak dapat dicoba ulang — bentuk respons bersifat deterministik untuk sebuah versi sidecar tertentu. Verifikasi versi sidecar terhadap minApiVersion klien, periksa proxy atau gateway perantara mana pun, lalu deploy ulang sidecar yang kompatibel.

SpectrumNotAvailableException

SpectrumNotAvailableException memperluas RuntimeException secara langsung dan bukan bagian dari hierarki SpectrumApiException. Eksepsi ini menandakan bahwa sidecar tak terjangkau atau gagal pemeriksaan kesehatan, sebelum badan kesalahan SPEC-* apa pun dapat dikembalikan.

Kapan dilemparkan

• Circuit breaker terbuka, atau semua upaya retry habis (SpectrumClient).
• Kesalahan transport HTTP terjadi saat menghubungi sidecar; ClientExceptionInterface PSR-18 yang mendasarinya dirangkai sebagai eksepsi sebelumnya.
• Sebuah stream server-sent-events diminta sementara sidecar melaporkan dirinya tidak tersedia (SseStreamClient).

Properti

Tipe ini tidak membawa metadata SPEC-*. Pesan disusun sebagai "Spectrum sidecar unavailable: {reason}", dengan integer code opsional dan throwable previous yang terangkai.

Pemulihan

Tangkap ini ketika Spectrum bersifat opsional dan jatuh kembali ke pemrosesan PHP-native (degradasi anggun). Ketika Spectrum diperlukan, pastikan sidecar aktif dan terjangkau, lalu jalankan ulang panggilan tersebut.

Lihat juga

• Indeks referensi kesalahan
• Enkripsi dan izin
• Indeks basis pengetahuan