> ## Documentation Index
> Fetch the complete documentation index at: https://docs.starfort.io/llms.txt
> Use this file to discover all available pages before exploring further.

# エラーと状態

> エラーレスポンスと、Guard API の呼び出しを停止させ得るプラットフォームの状態について説明します。

## エラーのエンベロープ

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

```json theme={null}
{
  "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` ヘッダーと、キーがまだアクティブであることを確認してください。[認証](/ja/v1.2/api/authentication)を参照してください。

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

呼び出しは、Guardian が実行される前に事前検証を通過します。以下は、それを停止させ得る状態を、チェックされる順序で示したものです。

| 状態                     | 発生したこと                                                                           | 対処方法                                                                                                                 |
| ---------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **認証の失敗**              | キーが欠落、見つからない、または取り消された。                                                          | **401** を返します（上記）。                                                                                                   |
| **API が見つからない**        | キーに一致する API がない。                                                                 | 正しいキーを使用しているか確認してください。                                                                                               |
| **API キーが非アクティブ**      | 管理者がキーをオフに切り替えました。                                                               | 再有効化するか、別のキーを使用してください。[API キーの管理](/ja/v1.2/admin/api-keys)を参照してください。                                                 |
| **Kill Switch がアクティブ** | 管理者が組織、プロジェクト、または Guardian で [Kill Switch](/ja/v1.2/admin/kill-switch) を有効化しました。 | トラフィックは意図的にブロックされています。無効化されるまで待ってください。                                                                               |
| **未対応の `processType`** | 値が Guardian の宣言したものではありません。                                                      | サポートされているプロセスタイプを使用してください。エラーメッセージにそれらが一覧表示されます。                                                                     |
| **Input Type が未有効**    | コンテンツパートのタイプが Guardian で有効になっていません。                                              | Guardian で有効化するか、そのパートを送信しないでください。（ファイルパートがここで失敗するのは BLOCK 処理の場合のみです — [マルチモーダル](/ja/v1.2/api/multimodal)を参照してください。） |
| **制限の超過**              | テキスト長またはファイルサイズが Guardian の制限を超えています。                                            | ペイロードを削減してください。                                                                                                      |
| **Guardian の障害**       | Guardian エンドポイントに到達できないか、エラーが発生しました。                                             | バックオフを伴って再試行してください。                                                                                                  |

**非アクティブ**と **Kill Switch** のレスポンスは、ブロックがどこ（組織／プロジェクト／Guardian）から来たのかを意図的に**明かしません**。これはリソースの列挙を防ぐためです。その場所は監査ログにのみ記録されます。

<Note>
  上記の状態に対する正確な `error.code` の値と HTTP ステータスは、デプロイ環境によって異なる場合があります。上記の **401** 認証レスポンスが安定した契約です。常にまず HTTP ステータスで分岐し、次に `error.details` で分岐してください。
</Note>

## トレースされる内容

キーがアクティブであることが確認された後の失敗 — 未対応の `processType`、Input Type の不一致、制限違反、Guardian の障害 — は [Opticon トレース](/ja/v1.2/admin/monitoring-opticon)として**記録されます**（エラー情報 + 入力メタデータ。ただしメッセージ本文やファイル内容は記録されません）。それより前の状態 — 認証の失敗、API が見つからない、非アクティブなキー、Kill Switch — は**トレースされません**。これらはセキュリティ／ガバナンスのイベントであり、別のログで処理されます。

## 推奨される処理

<Steps>
  <Step title="HTTP ステータスを確認する">200 = 評価済み。4xx／5xx = 未評価。</Step>
  <Step title="200 の場合は `action` で分岐する">PASS／MASK／BLOCK — [レスポンス形式](/ja/v1.2/api/response-format)を参照してください。</Step>
  <Step title="エラーの場合は `error.details` を確認する">リスク方針に応じて、フェイルクローズ（ブロック）またはフェイルオープン（許可）してください。</Step>
</Steps>