Skip to main content

​
エラーのエンベロープ

エラーは 200 以外のステータスと、次の形式で返されます。

​
フェイルクローズ：エラーは決してクリーンな結果ではない

Guard API はフェイルクローズです。Guardian が完全に分析できないリクエストは HTTP エラーを返します。空の検出結果を伴う 200 に格下げされることは決してありません。したがって、PASS は常に「分析済みで、何も検出されなかった」を意味し、障害が密かにバイパスに変わることはありません。Guardian 側の障害には 2 つのクラスがあります。
  • 入力エラー（4xx） — 入力そのものが処理できない（例：内容を抽出できない破損したファイル）。
  • 処理の失敗（5xx） — 入力は問題ないが、Guardian が完了できなかった（例：AI モデルの呼び出しが失敗またはタイムアウトした）。
部分的な失敗（複数のモデル呼び出しのうち一部が失敗）は、リクエスト全体のエラーとして扱われます。部分的な結果は「何も検出されなかった」と区別がつかないためです。

​
認証 — 401

欠落、無効、または取り消された API キーの場合、error.details: "API_KEY_INVALID" を伴った HTTP 401 が返されます。X-Starfort-Guard-Api-Key ヘッダーと、キーがまだアクティブであることを確認してください。認証を参照してください。

​
呼び出しを停止させる状態

呼び出しは、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` を確認する

リスク方針に応じて、フェイルクローズ（ブロック）またはフェイルオープン（許可）してください。