# エラー

problem+json のエラー形式、各ステータスコードの意味、失敗したリクエストをコードで処理する方法。

リクエストが失敗すると、PDF Blocks は標準的な HTTP ステータスコードと、何が問題だったかを示す機械可読な本文を返します。エラーは [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) の problem details に従うため、どのアクションが原因であっても同じ方法ですべての失敗を解析できます。

## problem+json モデル

エラーレスポンスは `Content-Type: application/problem+json` を持ち、次の形をしています。

| 属性 | 型 | 説明 |
| --------- | ------- | ----------------------------------------------- |
| `type`    | string  | 問題に関するドキュメントへの URL。       |
| `title`   | string  | 問題を人間が読める形で要約したもの。        |
| `status`  | integer | 本文にも反映される HTTP ステータスコード。     |
| `errors`  | object  | フィールド名とエラーメッセージの配列を対応付けたもの。 |

`type` の URL は常にステータスコードで終わるため（例：`https://www.pdfblocks.com/docs/api/v1/error/400`）、この URL または `status` で分岐できます。`errors` オブジェクトは、失敗が特定のリクエストフィールドに結び付いている場合（バリデーション）に存在します。無効な API キーのようなリクエスト全体に対する失敗では、省略されることがあります。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "file": [
      "Could not parse the PDF document. The file may be invalid or corrupt."
    ]
  }
}
```

## ステータスコード

| ステータス | 意味                        | 対応                          |
| ------ | ------------------------------ | ----------------------------------- |
| `400`  | バリデーションエラー               | 該当するフィールドを修正して再送信してください。    |
| `401`  | 未認証                   | 有効な `X-API-Key` を送信してください。           |
| `404`  | 見つかりません                      | アクションのルートとホストを確認してください。    |
| `406`  | 受理できない `Accept`          | サポートされている形式をリクエストしてください。         |
| `402`  | 支払いが必要 *(予約済み)*  | 請求またはクォータの問題を解決してください。       |
| `403`  | 禁止 *(予約済み)*         | このキーはこの呼び出しを許可されていません。  |
| `413`  | ペイロードが大きすぎる              | より小さいファイルを送信してください。           |
| `429`  | リクエストが多すぎる *(予約済み)* | 間隔を空けて再試行してください。                 |
| `5xx`  | サーバーエラー（まれ）            | バックオフして再試行してください。                 |

### 400：バリデーションエラー

パラメーターが無効か、`file` が読み取り可能な PDF ではありません。`errors` オブジェクトが、問題のある各フィールドを示します。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/400",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "line_1": ["The field line_1 must be a string with a maximum length of 32."]
  }
}
```

`errors` をフィールドごとに読み、入力を修正してから再送信してください。変更を加えない限り、`400` は再試行しても成功しません。

### 401：未認証

`X-API-Key` ヘッダーが欠けているか、形式が誤っているか、有効なキーではありません。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/401",
  "title": "The request is missing a valid API key.",
  "status": 401
}
```

[ダッシュボード](https://dashboard.pdfblocks.com) の有効なキーを `X-API-Key` ヘッダーに設定し、リクエストは HTTPS 経由で送信してください。詳細は [認証](/docs/api/authentication) を参照してください。

### 404：見つかりません

パスがどのアクションにも一致しません。多くの場合、アクション名のタイプミスか、バージョンのセグメントが抜けています。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/404",
  "title": "The requested resource was not found.",
  "status": 404
}
```

ルート（例：`/v1/add_text_watermark`）と、呼び出し先が有効な [ベース URL](/docs/api/regions-and-data-residency) であることを確認してください。

### 406：受理できない `Accept`

複数のドキュメントを返すアクションが、満たせない `Accept` ヘッダーを受け取りました。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/406",
  "title": "The requested Accept header cannot be satisfied.",
  "status": 406
}
```

サポートされている形式（`application/zip`、`application/json`、`multipart/mixed`）のいずれかをリクエストするか、`Accept` を省略してデフォルトの ZIP を取得してください。詳細は [レスポンスフォーマット](/docs/api/response-formats) を参照してください。

### 413：ペイロードが大きすぎる

プランごとに、1つの入力ドキュメントの最大サイズが決まっています。Free では5MB、それ以外のプランでは10MBです（[料金](/pricing) を参照）。この上限を超える本文を持つリクエストは、処理前に拒否されます。`429` とは異なり、`413` は再試行しても成功しません。より小さいファイルを送信するか、上限の引き上げが定期的に必要な場合はご相談ください。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/413",
  "title": "This request exceeds your plan's maximum document size of 10 MB.",
  "status": 413
}
```

### 予約済みのステータスコード

<Note>
  **将来に向けた仕様です。** `402`、`403`、`429` の各レスポンスは API 契約の一部ですが、現時点ではまだ強制されていません。有効化されたときにすぐクライアントが対応できるよう、今のうちに処理しておいてください。使用量とレート制限の詳細は [レート制限と使用量](/docs/api/rate-limits-and-usage) をご覧ください。
</Note>

**`402`：支払いが必要。** プランにおける請求またはクォータの条件です。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/402",
  "title": "Payment is required to complete this request.",
  "status": 402
}
```

**`403`：禁止。** キーは有効ですが、このリソースの利用を許可されていません。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/403",
  "title": "You do not have permission to access this resource.",
  "status": 403
}
```

**`429`：リクエストが多すぎる。** プランのレート許容量を超えました。

```json
{
  "type": "https://www.pdfblocks.com/docs/api/v1/error/429",
  "title": "Too many requests. Please retry later.",
  "status": 429
}
```

### 5xx：サーバーエラー

`5xx` ステータスはこちら側の問題を示すもので、まれにしか発生しません。一時的な問題であるため、同じリクエストを[指数バックオフ](/docs/api/rate-limits-and-usage)を付けて再試行してください。

## コードでのエラー処理

本文を一度だけ解析し、`status`（または `type` の末尾のステータス）で分岐します。

- **`400`**：`errors` オブジェクトを読み、各メッセージを対応するフィールドに突き合わせて入力を修正します。むやみに再試行しないでください。同じリクエストは再び失敗します。
- **`401`、`403`、`404`、`406`**：リクエスト自体に誤りがあります。ヘッダー、ルート、または `Accept` を修正して再送信してください。変更せずに再試行しても解決しません。
- **`402`、`413`**：アカウントまたはサイズに関する条件です。請求の問題を解決するか、より小さいファイルを送信してください。そのままでは再試行しても成功しません。
- **`429`** と **`5xx`**：一時的なものです。指数バックオフで再試行し、`Retry-After` ヘッダーがある場合はそれに従い、試行回数の上限を設けてください。詳細は [レート制限と使用量](/docs/api/rate-limits-and-usage) をご覧ください。

`errors` オブジェクトが存在する場合は必ず読んでください。修正すべき内容が正確に示されています。