エラーのエンベロープ
エラーは 200 以外のステータスと、次の形式で返されます。このページは同期 Guard API のエラーを扱います。S3 連携の非識別化バッチのエラー規約 — 受付時点の HTTP エラーと処理時点のジョブ失敗（
error.code）の区別 — についてはバッチのエラーを参照してください。フェイルクローズ：エラーは決してクリーンな結果ではない
Guard API はフェイルクローズです。Guardian が完全に分析できないリクエストは HTTP エラーを返します。空の検出結果を伴う200 に格下げされることは決してありません。したがって、PASS は常に「分析済みで、何も検出されなかった」を意味し、障害が密かにバイパスに変わることはありません。Guardian 側の障害には 2 つのクラスがあります。
- 入力エラー（4xx） — 入力そのものが処理できない（例：内容を抽出できない破損したファイル）。
- 処理の失敗（5xx） — 入力は問題ないが、Guardian が完了できなかった（例：AI モデルの呼び出しが失敗またはタイムアウトした）。
トレース記録の失敗（Fail-Closed プロジェクト）
v1.3 から、プロジェクトは Opticon フェイルセーフ ポリシーを Fail-Closed に設定できます。リクエストの分析は完了したもののトレースの記録が最終的に失敗した場合、記録なしで通過させる代わりにリクエストが BLOCK に格下げされます。記録の試行は有界（時間・リトライ上限）なので、Opticon の障害はレイテンシ増加とブロックとして現れるだけで、レスポンスがハングすることはありません。デフォルトの Fail-Open では呼び出し元にとって何も変わりません — 判定はそのまま返され、記録のみが失われます。認証 — 401
欠落、無効、または取り消された API キーの場合、error.details: "API_KEY_INVALID" を伴った HTTP 401 が返されます。X-Starfort-Guard-Api-Key ヘッダーと、キーがまだアクティブであることを確認してください。認証を参照してください。
呼び出しを停止させる状態
呼び出しはまず、ゲートウェイの事前検証（認証・キー状態・Kill Switch・processType）を通過します。コンテンツに対する検査ポリシー — 未対応ファイルの処理と検査制限（テキスト長・ファイルサイズ） — は、v1.4 からは Guardian が単一のポイントで強制し、最上位の入力だけでなく、ファイルから抽出されたテキストやアーカイブ内部のメンバーにも同じルールが適用されます。以下は、呼び出しを停止させ得る状態を、チェックされる順序で示したものです。
非アクティブと Kill Switch のレスポンスは、ブロックがどこ（組織／プロジェクト／Guardian）から来たのかを意図的に明かしません。これはリソースの列挙を防ぐためです。その場所は監査ログにのみ記録されます。
上記の状態に対する正確な
error.code の値と HTTP ステータスは、デプロイ環境によって異なる場合があります。上記の 401 認証レスポンスが安定した契約です。常にまず HTTP ステータスで分岐し、次に error.details で分岐してください。トレースされる内容
キーがアクティブであることが確認された後の失敗 — 未対応のprocessType、Input Type の不一致、制限違反、Guardian の障害 — は Opticon トレースとして記録されます（エラー情報 + 入力メタデータ。ただしメッセージ本文やファイル内容は記録されません）。それより前の状態 — 認証の失敗、API が見つからない、非アクティブなキー、Kill Switch — はトレースされません。これらはセキュリティ／ガバナンスのイベントであり、別のログで処理されます。
推奨される処理
1
HTTP ステータスを確認する
200 = 評価済み。4xx／5xx = 未評価。
2
200 の場合は `action` で分岐する
PASS／MASK／BLOCK — レスポンス形式を参照してください。
3
エラーの場合は `error.details` を確認する
リスク方針に応じて、フェイルクローズ（ブロック）またはフェイルオープン（許可）してください。