# APIエラーハンドリング — エラータイプ、コード、doc_url

> すべてのv1エラーは、type、code、message、doc_urlを含むJSONオブジェクトとして返されます。このページでは、エラータイプの全分類と個々のエラーコードを網羅しており、返されたdoc_urlのリンク先となります。

失敗したv1リクエスト（2xx以外のレスポンス）はすべて、以下に示す同一のJSON構造を返します。このページは、各エラーの`doc_url`がリンクする先でもあります。各コードには固有のアンカーセクションがあるため、実際のエラーレスポンスから`doc_url`をたどると、該当コードの説明に直接移動します。

## エラーの構造

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "A required parameter is missing.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
```

- `type` — このエラーが属する大まかなカテゴリです（下記の表を参照）。個々の`code`をすべてチェックしなくても、エラーハンドリングコードで大まかな分岐（「認証の問題か、バリデーションの問題か」）を行うのに役立ちます。
- `code` — 特定の安定したエラー識別子です。コード内でマッチングに使用するもので、後で`message`の文言が改善されても変更されることはありません。
- `message` — 人間が読める説明です。ログやデバッグに役立ちますが、解析を目的としたものではありません。
- `doc_url` — このページの該当`code`のセクションへの直接リンクです。
- `param` — バリデーションエラー（`missing_parameter`、`invalid_parameter`、`duplicate_field_name`）の場合にのみ存在し、エラーの原因となったリクエストフィールドを指定します。該当しない場合は、`null`ではなく、フィールド自体が省略されます。

## エラータイプ

各 `code` は、1つの `type` にのみ属します。

| タイプ | 意味 |
| --- | --- |
| authentication_error | リクエストの認証方法（または認証の有無）に問題があります。 |
| invalid_request_error | リクエスト自体が不正です（パラメータの欠落または無効）。 |
| not_found_error | URLで指定されたリソース（ドキュメント、バッチ、テンプレートID）が存在しないか、アカウントに属していません。 |
| insufficient_credits | アカウントに、リクエストされた（有料）アクションを実行するための十分なクレジットがありません。 |
| rate_limit_error | このエンドポイントカテゴリのリクエストレートを超えました。詳細は レート制限 をご覧ください。 |
| internal_error | サーバー側で問題が発生しました（お客様側の問題ではありません）。 |

## 特別なケース: `processing_error`

`processing_error` は、トップレベルの `{"error": ...}` レスポンスで見られる `type` では**ありません**。これ自体がAPIコールを失敗させることは決してありません。代わりに、バッチ内で抽出できなかった単一のドキュメントを説明するものです。正常に処理された同じバッチ内の他のドキュメントと共に、ステータス200 OKの `GET /batches/{batch_name}/results` レスポンス内で、そのドキュメントに `"status": "failed"` として反映されているのを確認できます。成功したAPIコール内のドキュメントレベルの失敗を、バッチ全体を再試行すべきエラーとして扱わないでください。各ドキュメントの個別の `status` を確認してください。

## エラーコード

### missing_api_key

**タイプ:** `authentication_error` · **HTTPステータス:** 401

APIキーが提供されていません。`Authorization: Bearer <key>` として送信してください。

### invalid_api_key

**タイプ:** `authentication_error` · **HTTPステータス:** 401

提供されたAPIキーが無効か、そのアカウントが無効になっています。

### plan_required

**タイプ:** `authentication_error` · **HTTPステータス:** 403

FreeプランではこのAPIは利用できません。Basic以上にアップグレードしてください。

### missing_parameter

**タイプ:** `invalid_request_error` · **HTTPステータス:** 400

必須パラメータが不足しています。エラーオブジェクトの `param` で該当パラメータを確認してください。

### invalid_parameter

**タイプ:** `invalid_request_error` · **HTTPステータス:** 400

パラメータの値が無効です。詳細は `param` と `message` を確認してください。このコードは、不正な `crop` 文字列、範囲外の `limit`、処理対象がないバッチなど、さまざまなケースをカバーする汎用コードです。

### duplicate_field_name

**タイプ:** `invalid_request_error` · **HTTPステータス:** 400

このテンプレートに同じ名前のフィールドがすでに存在します。フィールド名はテンプレート内で一意である必要があります。

### idempotency_key_reused

**タイプ:** `invalid_request_error` · **HTTPステータス:** 400

この `Idempotency-Key` は、異なるパラメータのリクエストですでに使用されています。本当に異なるリクエストには新しいキーを使用してください。詳細な動作は[冪等性](/developers/guides/idempotency)を参照してください。

### document_not_found

**タイプ:** `not_found_error` · **HTTPステータス:** 404

指定されたIDのドキュメントが見つかりませんでした（存在しないか、アカウントに属していません）。

### batch_not_found

**タイプ:** `not_found_error` · **HTTPステータス:** 404

指定された名前のバッチが見つかりませんでした。

### template_not_found

**タイプ:** `not_found_error` · **HTTPステータス:** 404

指定されたIDのテンプレートが見つかりませんでした。

### insufficient_credits

**タイプ:** `insufficient_credits` · **HTTPステータス:** 402

この操作を実行するためのクレジットが不足しています。再試行する前に、`GET /account` で現在の `available_credits` を確認してください。

### rate_limit_exceeded

**タイプ:** `rate_limit_error` · **HTTPステータス:** 429

リクエストが多すぎます。速度を落とし、ウィンドウがリセットされた後に再試行してください。`X-RateLimit-Reset` レスポンスヘッダーと[レート制限](/developers/guides/rate-limits)ガイドを参照してください。

### internal_error

**タイプ:** `internal_error` · **HTTPステータス:** 500

予期しないエラーが発生しました。これが続く場合は、お客様ではなく当社側の問題です。再現可能であれば、お問い合わせの際にその情報を含めていただくと役立ちます。

---

Source: https://imagetotable.ai/ja/developers/guides/errors