Accelerator hataları

Kapsam

Bu beş istisna, isteğe bağlı Spectrum (Prism) donanım-hızlandırıcı yardımcısından gelen hataları yüzeye çıkarır. Yardımcıya, HTTP üzerinden NextPDF\Accelerator\SpectrumClient aracılığıyla erişilir; hata yanıtları, kanonik bir taksonomiden makinede okunabilir bir SPEC-* kodu taşır ve istemci, o kodu aşağıdaki istisna türlerinden birine eşler.

Çoğu NextPDF istisnasının aksine, Accelerator istisnaları getContext() yöntemini uygulamaz. PHP’nin RuntimeException sınıfını genişletir ve durumlarını türlü, readonly genel özellikler olarak sunar. Hata alanlarını, alt sınıfları yakalayarak değil, specCode önekini eşleştirerek (örneğin str_starts_with($e->specCode, 'SPEC-AUTH-')) ayırt edin — alt sınıf hiyerarşisi dahilidir ve ikincil sürümlerde değişebilir.

SpectrumApiException

SpectrumApiException, her yardımcı hata yanıtı için temel türdür. Daha özel bir alt sınıfı olmayan herhangi bir SPEC-* kodu için doğrudan fırlatılır ve tüm yardımcı hatalarını bir kerede işlemek için yakaladığınız türdür.

Ne zaman fırlatılır

• Yardımcı, yapılandırılmış bir SPEC-* hata gövdesi döndürür. SpectrumResponseParser, gövdenin kodunu çözer ve SPEC-AUTH-* ile SPEC-OOM-* (aşağıdaki alt sınıflara eşlenir) dışındaki tüm kodlar için bu türü fırlatır. Bu temel türe belgelenmiş eşlemeler şunları içerir: SPEC-INDEX-* (koleksiyon dizini), SPEC-KMS-* (anahtar-yönetimi sağlayıcısı), SPEC-OCR-*, SPEC-MODEL-* ve SPEC-BILLING-*.
• SPEC-IO-001 — yanıt gövdesi geçerli JSON değil (httpStatus 502).
• SPEC-IO-002 — yardımcı API sürümü, yapılandırılmış minApiVersion ile uyumsuz.
• SPEC-SEC-001 — bir belge yükü, yapılandırılmış boyut bütçesini aşar (SpectrumSecurityPolicy::validatePayloadSize()).
• SPEC-SEC-003 — bir çalışma alanı yolu, dolaşım denetimini geçemez (SpectrumSecurityPolicy::validateWorkspacePath()).
• SPEC-SEC-004 — bir iş tanımlayıcısı boş, fazla uzun ya da opak-kimlik izin-listesinin dışında karakterler içerir (SpectrumSecurityPolicy::validateJobId()).

Özellikler

Özellik	Tür	Anlam
specCode	string	Makinede okunabilir SPEC-* hata kodu (örneğin SPEC-INDEX-003).
httpStatus	int	Yardımcının döndürdüğü HTTP durumu; varsayılan olarak 500. Ayrıca istisna kodu olarak kullanılır.
retryable	bool	İşlemin güvenle yeniden denenip denenemeyeceği. Varsayılan olarak false.
traceId	?string	X-Trace-Id yanıt başlığından korelasyon izleme kimliği ya da null.

İleti, "[{specCode}] {message}" olarak oluşturulur. Üç yardımcı yüklem, yaygın alanları sınıflandırır: isKmsError() (SPEC-KMS-*), isIndexError() (SPEC-INDEX-*) ve isOcrError() (SPEC-OCR-*).

Çözüm

1. Başarısız olan alanı tanımlamak için specCode değerini okuyun; önekine göre dallanın.
2. retryable değerine uyun: yalnızca true olduğunda yeniden deneyin ve yapılandırma veya uyumluluk kusurlarını işaret eden bir SPEC-SEC-* ya da SPEC-IO-002 kodunda asla yeniden denemeyin.
3. Hatayı, bir kusur raporunda yardımcı tarafı tanılamalarla ilişkilendirmek için günlüklerinizde traceId değerini yakalayın.

Spectrum alt sınıfları

Aşağıdaki türler SpectrumApiException sınıfının final alt sınıflarıdır. Bunları doğrudan yakalamak yerine SpectrumApiException türünü yakalayın (ya da specCode değerini eşleştirin).

SpectrumAuthenticationException

Bir lisans, belirteç ya da dağıtım bağı hatasını gösteren SPEC-AUTH-* kodları için fırlatılır. SpectrumResponseParser, yanıt kodu SPEC-AUTH- ile başladığında onu fırlatır.

Belgelenmiş nedenler şunları içerir: SPEC-AUTH-001 (geçersiz lisans Ed25519 imzası), SPEC-AUTH-002 (lisans süresi doldu ve ek süre dışında), SPEC-AUTH-003 (dağıtım yuvası uyuşmazlığı), SPEC-AUTH-004 (geçersiz JWT Bearer belirteci), SPEC-AUTH-006 (lisans düşürüldü, ek süre doldu) ve SPEC-AUTH-007 (satın alınan lisansa dahil olmayan özellik).

Temel türle aynı özellikleri taşır ancak yapıcı, retryable değerini false olarak sabitler ve httpStatus değerini varsayılan olarak 403 yapar.

Çözüm. Bu hatalar, operatör müdahalesi olmadan asla yeniden denenebilir değildir. Lisansı yenileyin veya düzeltin, Bearer belirtecini tazeleyin ya da dağıtım yuvasını hizalayın, sonra çağrıyı yeniden çalıştırın.

SpectrumResourceException

GPU veya CPU belleği tükendiğinde SPEC-OOM-* kodları için fırlatılır. SpectrumResponseParser, herhangi bir SPEC-OOM- öneki için onu fırlatır ve DegradePolicy::FailFast ayarı, sessizce daha düşük bir donanım katmanına düşmek yerine onu fırlatır.

Yapıcı, retryable değerini true olarak sabitler ve httpStatus değerini varsayılan olarak 503 yapar.

Çözüm. Bu istisna yeniden denenebilir. İşi kuyruğa alın ve diğer işler tamamlanıp kaynakları serbest bıraktıktan sonra yeniden deneyin ya da düşürülmüş bir katman iş yükü için kabul edilebilirse DegradePolicy değerini AllowWithLog / WarnAndProceed olarak gevşetin.

SpectrumProtocolException

Bir yardımcı yanıtı JSON olarak ayrıştığında ancak beklenen protokol biçimiyle eşleşmediğinde fırlatılır. Her zaman specCode SPEC-IO-003 ve httpStatus 502 kullanır; retryable değeri false olarak sabitlenmiştir.

Bu, SPEC-IO-001 (geçersiz JSON) durumundan farklıdır: burada JSON iyi-biçimlidir ancak yapısal olarak yanlıştır; bu genellikle gövdeyi yeniden yazan bir proxy veya ağ geçidini, uyumsuz bir yardımcı sürümünü ya da bozuk bir yanıtı gösterir.

Çözüm. Yeniden denenebilir değil — yanıt biçimi, belirli bir yardımcı sürümü için belirleyicidir. Yardımcı sürümünü istemcinin minApiVersion değerine karşı doğrulayın, aradaki proxy veya ağ geçidini inceleyin, sonra uyumlu bir yardımcıyı yeniden dağıtın.

SpectrumNotAvailableException

SpectrumNotAvailableException, doğrudan RuntimeException sınıfını genişletir ve SpectrumApiException hiyerarşisinin bir parçası değildir. Herhangi bir SPEC-* hata gövdesi döndürülemeden önce yardımcıya erişilemediğini ya da bir sağlık denetimini geçemediğini işaret eder.

Ne zaman fırlatılır

• Devre kesici açıktır ya da tüm yeniden-deneme denemeleri tükenmiştir (SpectrumClient).
• Yardımcıya başvururken bir HTTP taşıma hatası oluşur; temeldeki PSR-18 ClientExceptionInterface, önceki istisna olarak zincirlenir.
• Yardımcı kendisini kullanılamaz bildirirken bir sunucu-gönderimli-olaylar akışı istenir (SseStreamClient).

Özellikler

Bu tür hiçbir SPEC-* üst verisi taşımaz. İleti, isteğe bağlı bir tam sayı code ve zincirlenmiş bir previous fırlatılabilir nesneyle birlikte "Spectrum sidecar unavailable: {reason}" olarak oluşturulur.

Çözüm

Spectrum isteğe bağlıyken bunu yakalayın ve PHP-yerel işlemeye (nazik düşürme) geri dönün. Spectrum gerekli olduğunda, yardımcının çalıştığını ve erişilebilir olduğunu doğrulayın, sonra çağrıyı yeniden çalıştırın.

Ayrıca bakınız

• Hata başvurusu dizini
• Şifreleme ve izinler
• Bilgi tabanı dizini