Accelerator 錯誤

適用範圍

這五個例外狀況揭露來自選用的 Spectrum（Prism）硬體加速器 sidecar 的失敗。該 sidecar 透過 NextPDF\Accelerator\SpectrumClient 經由 HTTP 連接；錯誤回應會攜帶來自標準分類法的機器可讀 SPEC-* 代碼，而用戶端會把該代碼對應到下列其中一種例外狀況型別。

與大多數 NextPDF 例外狀況不同，Accelerator 例外狀況不實作 getContext()。它們繼承 PHP 的 RuntimeException，並以具型別、readonly 的公開屬性揭露其狀態。請以比對 specCode 前綴的方式（例如 str_starts_with($e->specCode, 'SPEC-AUTH-')）來區分錯誤領域，而非攔截子類別——子類別階層屬於內部實作，可能在次要版本中變更。

SpectrumApiException

SpectrumApiException 是每一個 sidecar 錯誤回應的基底型別。任何沒有更具體子類別的 SPEC-* 代碼都會直接拋出它，而你要一次處理所有 sidecar 錯誤時，攔截的就是這個型別。

何時被拋出

• sidecar 回傳結構化的 SPEC-* 錯誤主體。SpectrumResponseParser 會解碼主體，並對除了 SPEC-AUTH-* 與 SPEC-OOM-*（對應到下方子類別）以外的所有代碼拋出此型別。對應到此基底型別的已載明映射包括 SPEC-INDEX-*（集合索引）、SPEC-KMS-*（金鑰管理提供者）、SPEC-OCR-*、SPEC-MODEL-* 與 SPEC-BILLING-*。
• SPEC-IO-001 — 回應主體並非有效的 JSON（httpStatus 502）。
• SPEC-IO-002 — sidecar API 版本與所設定的 minApiVersion 不相容。
• SPEC-SEC-001 — 文件酬載超出所設定的大小預算（SpectrumSecurityPolicy::validatePayloadSize()）。
• SPEC-SEC-003 — 工作區路徑未通過遍歷檢查（SpectrumSecurityPolicy::validateWorkspacePath()）。
• SPEC-SEC-004 — 工作識別碼為空、過長，或含有不在不透明 ID 允許清單內的字元（SpectrumSecurityPolicy::validateJobId()）。

屬性

屬性	型別	意義
specCode	string	機器可讀的 SPEC-* 錯誤代碼（例如 SPEC-INDEX-003）。
httpStatus	int	sidecar 回傳的 HTTP 狀態；預設為 500。同時用作例外狀況的代碼。
retryable	bool	該操作是否可安全重試。預設為 false。
traceId	?string	來自 X-Trace-Id 回應標頭的關聯追蹤 ID，或 null。

訊息組成為 "[{specCode}] {message}"。三個輔助述詞會將常見領域分類：isKmsError()（SPEC-KMS-*）、isIndexError()（SPEC-INDEX-*）與 isOcrError()（SPEC-OCR-*）。

解法

1. 讀取 specCode 以辨識失敗的領域；依其前綴分支處理。
2. 尊重 retryable：只有在其為 true 時才重試，且在 SPEC-SEC-* 或 SPEC-IO-002 代碼上絕不重試，因為它們表示組態或相容性缺陷。
3. 在你的日誌中擷取 traceId，以便在缺陷回報中將該失敗與 sidecar 端的診斷相互關聯。

Spectrum 子類別

下列型別是 SpectrumApiException 的 final 子類別。請攔截 SpectrumApiException（或比對 specCode），而非直接攔截這些子類別。

SpectrumAuthenticationException

對 SPEC-AUTH-* 代碼拋出，代表授權、權杖或部署綁定失敗。每當回應代碼以 SPEC-AUTH- 開頭時，SpectrumResponseParser 就會拋出它。

已載明的原因包括 SPEC-AUTH-001（無效的授權 Ed25519 簽章）、SPEC-AUTH-002（授權過期且超出寬限期）、SPEC-AUTH-003（部署插槽不符）、SPEC-AUTH-004（無效的 JWT Bearer 權杖）、SPEC-AUTH-006（授權降級、寬限期已過）與 SPEC-AUTH-007（功能未包含在所購買的授權中）。

它攜帶與基底型別相同的屬性，但建構式會將 retryable 釘為 false，並把 httpStatus 預設為 403。

解法。 這些錯誤若無維運人員介入，絕不可重試。請續訂或更正授權、重新整理 Bearer 權杖，或對齊部署插槽，然後重新執行該呼叫。

SpectrumResourceException

當 GPU 或 CPU 記憶體耗盡時，對 SPEC-OOM-* 代碼拋出。SpectrumResponseParser 會對任何 SPEC-OOM- 前綴拋出它，而 DegradePolicy::FailFast 設定會拋出它，而非悄悄降級到較低的硬體層級。

建構式會將 retryable 釘為 true，並把 httpStatus 預設為 503。

解法。 此例外狀況可重試。請將工作排入佇列，等其他工作完成並釋出資源後再重試；若降級層級對該工作負載而言可接受，也可將 DegradePolicy 放寬為 AllowWithLog / WarnAndProceed。

SpectrumProtocolException

當 sidecar 回應可解析為 JSON、但與預期的協定形狀不符時拋出。它一律使用 specCode SPEC-IO-003 與 httpStatus 502，並將 retryable 釘為 false。

這與 SPEC-IO-001（無效的 JSON）不同：在此，JSON 是格式正確的，但結構錯誤，這通常表示有代理或閘道重寫了主體、sidecar 版本不相容，或回應損毀。

解法。 不可重試——對於給定的 sidecar 版本，回應形狀是確定的。請比對 sidecar 版本與用戶端的 minApiVersion、檢視任何中介代理或閘道，然後重新部署相容的 sidecar。

SpectrumNotAvailableException

SpectrumNotAvailableException 直接繼承 RuntimeException，且不屬於 SpectrumApiException 階層。它代表 sidecar 無法連線或健康檢查失敗，發生在任何 SPEC-* 錯誤主體得以回傳之前。

何時被拋出

• 斷路器處於開啟狀態，或所有重試嘗試都已用盡（SpectrumClient）。
• 連接 sidecar 時發生 HTTP 傳輸錯誤；底層的 PSR-18 ClientExceptionInterface 會被鏈結為前一個例外狀況。
• 在 sidecar 回報自身不可用時請求 server-sent-events 串流（SseStreamClient）。

屬性

此型別不攜帶任何 SPEC-* 中介資料。訊息組成為 "Spectrum sidecar unavailable: {reason}"，並可選地帶有整數 code 與一個鏈結的 previous throwable。

解法

當 Spectrum 是選用的時，請攔截它並退回到 PHP 原生處理（優雅降級）。當 Spectrum 是必要的時，請確認 sidecar 已啟動且可連線，然後重新執行該呼叫。

另請參閱

• 錯誤參考索引
• 加密與權限
• 知識庫索引