> ## 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.

# バッチのエラー

> Starfort バッチ非個人化 API のエラー契約。取り込み時の HTTP エラーと処理時の error.code によるジョブ失敗の意味と対処を解説します (Starfort v1.4 版)

バッチのエラーは、発生時点によって 2 つの層に分かれます:

* **リクエスト・受付時点** — 受付が拒否され、**ジョブは作成されません**。HTTP エラーレスポンスとして即時に返されます。
* **処理時点** — 受付は成功したものの検査を完了できず、ジョブが `FAILED` として確定します。理由は[ジョブ照会](/ja/v1.4/api/batch/jobs)レスポンスの `error`（`code` / `message` / `details`）で提供されます。

**BLOCK はエラーではありません** — 検査を完了した正常な判定であるため、`COMPLETED` + `action: "BLOCK"` として返されます。[バッチ概要](/ja/v1.4/api/batch/overview)を参照してください。

## リクエスト・受付時点（HTTP レスポンス）

エラーのエンベロープは、インライン [Guard API のエラー形式](/ja/v1.4/api/errors)と同一です:

```json theme={"dark"}
{
  "ok": false,
  "error": {
    "code": "S3_TARGET_NOT_ALLOWED",
    "message": "tgt_s3_url is outside the allowed write scope",
    "details": "connection 's3-prod' allows WRITE on s3://your-bucket/deidentified/*"
  }
}
```

| HTTP | `error.code`                   | 状況                                                                            |
| ---- | ------------------------------ | ----------------------------------------------------------------------------- |
| 401  | `UNAUTHORIZED`                 | API Key の未提供または無効                                                             |
| 403  | （アクティブ状態関連のコード）                | 無効化、または [Kill Switch](/ja/v1.4/admin/kill-switch) の発動中 — 発動中は作成・照会がどちらも拒否されます |
| 400  | `BAD_REQUEST`                  | リクエスト形式の誤り — URL 形式の違反、未対応の `process_type` など                                 |
| 400  | `S3_CONNECTION_NOT_CONFIGURED` | プロジェクトに [Storage Connection](/ja/v1.4/api/batch/storage-connection) が未登録      |
| 400  | `S3_TARGET_NOT_ALLOWED`        | `src` / `tgt` が許可範囲（バケット・パス・読み取り／書き込みモード）の外                                   |
| 404  | `NOT_FOUND`                    | 存在しないジョブ ID の照会                                                               |
| 502  | `BAD_GATEWAY`                  | Starfort 内部の一時的な障害 — リトライしてください                                               |

## 処理時点の失敗（ジョブの `error.code`）

ジョブ照会レスポンスの `status: "FAILED"` とともに、`error.code` として返されます。失敗したジョブは `tgt` に何も保存しません。

| `error.code`                                 | 状況                                                           |
| -------------------------------------------- | ------------------------------------------------------------ |
| `SRC_FETCH_FAILED`                           | 原本を読み取れなかった — オブジェクトの不存在、アクセス権限の拒否など                         |
| `SRC_UNSUPPORTED_TYPE`                       | 未対応の形式、または拡張子・内容の不一致（偽装ファイル）                                 |
| `FILE_TOO_LARGE` / `TEXT_TOO_LONG`           | ファイルサイズ・テキスト長の[制限](/ja/v1.4/api/batch/outputs-and-limits)を超過 |
| `GUARDIAN_CALL_FAILED` / `GUARDIAN_REJECTED` | 解析エンジンの処理失敗 — `details` に詳細な理由                               |
| `TGT_WRITE_FAILED`                           | 結果の保存に失敗 — 書き込み権限・容量など                                       |
| `KILL_SWITCH_ACTIVATED`                      | 受付後に Kill Switch が発動 — 待機中・進行中のジョブが成果物なしで失敗確定                |
| `JOB_EXPIRED`                                | リトライ上限内に処理が完了しなかった — 再受付してください                               |

## 推奨される処理

<Steps>
  <Step title="ジョブ作成の HTTP ステータスを確認する">202 = 受付済み（`job_id` を保管）。4xx／5xx = ジョブ未作成 — `error.code` で分岐し、リクエストを修正するかリトライしてください。</Step>
  <Step title="照会で `status` により分岐する">`COMPLETED` = 判定（`action`）を確認。`FAILED` = `error.code` で分岐。</Step>
  <Step title="失敗を処理する">`SRC_*` / `S3_*` 系はバケット・権限・ファイルを修正した上で再受付し、`GUARDIAN_*` / `JOB_EXPIRED` / 502 はバックオフを適用してリトライ（再受付）してください。</Step>
</Steps>