メインコンテンツへスキップ

​
エラーのエンベロープ

エラーは 200 以外のステータスと、次の形式で返されます。 
{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid credentials (getApiGuardGate)",
    "details": "API_KEY_INVALID"
  }
}

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

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 が実行される前に事前検証を通過します。以下は、それを停止させ得る状態を、チェックされる順序で示したものです。
状態発生したこと対処方法
認証の失敗キーが欠落、見つからない、または取り消された。401 を返します（上記）。
API が見つからないキーに一致する API がない。正しいキーを使用しているか確認してください。
API キーが非アクティブ管理者がキーをオフに切り替えました。再有効化するか、別のキーを使用してください。API キーの管理を参照してください。
Kill Switch がアクティブ管理者が組織、プロジェクト、または Guardian で Kill Switch を有効化しました。トラフィックは意図的にブロックされています。無効化されるまで待ってください。
未対応の processType値が Guardian の宣言したものではありません。サポートされているプロセスタイプを使用してください。エラーメッセージにそれらが一覧表示されます。
Input Type が未有効コンテンツパートのタイプが Guardian で有効になっていません。Guardian で有効化するか、そのパートを送信しないでください。（ファイルパートがここで失敗するのは BLOCK 処理の場合のみです — マルチモーダルを参照してください。）
制限の超過テキスト長またはファイルサイズが Guardian の制限を超えています。ペイロードを削減してください。
Guardian の障害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` を確認する

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