Accelerator のエラー

対象範囲

これら 5 つの例外は、オプションの Spectrum（Prism） ハードウェアアクセラレーターサイドカーからの失敗を表面化させます。サイドカーは NextPDF\Accelerator\SpectrumClient を通じて HTTP 経由で到達されます。エラー応答は、標準的なタクソノミー由来の機械可読な SPEC-* コードを保持し、クライアントはそのコードを以下の例外型の 1 つにマッピングします。

ほとんどの NextPDF 例外と異なり、Accelerator の例外は getContext() を 実装しません。PHP の RuntimeException を継承し、その状態を型付きの readonly public プロパティとして公開します。エラー領域を区別するには、サブクラスを捕捉するのではなく specCode プレフィックスを照合してください（例: str_starts_with($e->specCode, 'SPEC-AUTH-')）。サブクラス階層は内部的なものであり、マイナーバージョンで変更される可能性があります。

SpectrumApiException

SpectrumApiException は、すべてのサイドカーエラー応答の基底型です。これは、より具体的なサブクラスを持たないあらゆる SPEC-* コードに対して直接送出され、すべてのサイドカーエラーを一度に処理するために捕捉する型です。

送出される条件

• サイドカーが構造化された 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 — サイドカー API バージョンが、構成済みの minApiVersion と非互換である。
• SPEC-SEC-001 — ドキュメントペイロードが構成済みのサイズ予算を超えている （SpectrumSecurityPolicy::validatePayloadSize()）。
• SPEC-SEC-003 — ワークスペースパスがトラバーサルチェックに失敗する （SpectrumSecurityPolicy::validateWorkspacePath()）。
• SPEC-SEC-004 — ジョブ識別子が空、長すぎる、または opaque-ID 許可リストの外の文字を含む（SpectrumSecurityPolicy::validateJobId()）。

プロパティ

プロパティ	型	意味
specCode	string	機械可読の SPEC-* エラーコード（例: SPEC-INDEX-003）。
httpStatus	int	サイドカーが返した HTTP ステータス。デフォルトは 500。例外コードとしても使用されます。
retryable	bool	操作を安全に再試行できるかどうか。デフォルトは false。
traceId	?string	X-Trace-Id 応答ヘッダーからの相関トレース ID、または null。

メッセージは "[{specCode}] {message}" として構成されます。3 つのヘルパー述語が一般的な領域を分類します。isKmsError()（SPEC-KMS-*）、isIndexError() （SPEC-INDEX-*）、isOcrError()（SPEC-OCR-*）。

復旧

1. specCode を読み取って失敗した領域を特定し、そのプレフィックスで分岐してください。
2. retryable を尊重してください。true のときのみ再試行し、構成または互換性の不具合を示す SPEC-SEC-* または SPEC-IO-002 コードでは決して再試行しないでください。
3. サイドカー側の診断と失敗を不具合レポートで相関させるために、ログに traceId を捕捉してください。

Spectrum のサブクラス

以下の型は SpectrumApiException の final サブクラスです。これらを直接ではなく、 SpectrumApiException を捕捉する（または specCode で照合する）ようにしてください。

SpectrumAuthenticationException

SPEC-AUTH-* コードに対して送出され、ライセンス、トークン、またはデプロイメントバインディングの失敗を示します。SpectrumResponseParser は、応答コードが SPEC-AUTH- で始まる場合は常にこれを送出します。

文書化された原因には、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

サイドカー応答が JSON としてパースされるものの、期待されるプロトコル形状に一致しない場合に送出されます。これは常に specCode SPEC-IO-003 と httpStatus 502 を使用し、 retryable は false に固定されます。

これは SPEC-IO-001（不正な JSON）とは区別されます。ここでは JSON は整形式ですが構造的に誤っており、これは通常、本体を書き換えるプロキシまたはゲートウェイ、 非互換のサイドカーバージョン、または破損した応答を示します。

復旧。 再試行不可です。応答形状は、特定のサイドカーバージョンに対して決定的です。サイドカーバージョンをクライアントの minApiVersion と照合し、中間のプロキシまたはゲートウェイを検査してから、互換性のあるサイドカーを再デプロイしてください。

SpectrumNotAvailableException

SpectrumNotAvailableException は RuntimeException を直接継承し、 SpectrumApiException 階層の 一部ではありません。これは、SPEC-* エラー本体が返される前に、サイドカーが到達不能であるか、またはヘルスチェックに失敗したことを示します。

送出される条件

• サーキットブレーカーが開いている、またはすべての再試行が尽きた場合 （SpectrumClient）。
• サイドカーと通信中に HTTP トランスポートエラーが発生した場合。基盤となる PSR-18 ClientExceptionInterface が previous の例外としてチェーンされます。
• サイドカーが自身を利用不可と報告している間に server-sent-events ストリームが要求された場合（SseStreamClient）。

プロパティ

この型は SPEC-* メタデータを保持しません。メッセージは "Spectrum sidecar unavailable: {reason}" として構成され、オプションの整数 code とチェーンされた previous の throwable を伴います。

復旧

Spectrum がオプションの場合はこれを捕捉し、PHP ネイティブの処理にフォールバックしてください （graceful degradation）。Spectrum が必須の場合は、サイドカーが起動して到達可能であることを確認してから、呼び出しを再実行してください。

関連項目

• Error reference index
• Encryption and permissions
• Knowledge base index