> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# エラー

> BeatAPI の全エラーコードについて、HTTP ステータス、再試行可否、発生条件、クライアントの対処を説明します。

# エラー

BeatAPI は、定義済みのコードで失敗を報告します。`code` または `retryable` で分岐してください。`message` は原因を人に伝える英語の文です。第三者の名前、ステータスコード、エラー本文をそのまま返すことはありません。サポート用に `request_id` を保存してください。

## エラーオブジェクト

画像・動画タスク、`GET /v1/tasks/{task_id}`、機能、ワークフロー、`/v1/systemone`（別名 `/v1/decisions`）、`/v1/moderations`、`/v1/social-data/call`、`/v1/web/*` は、共通のエラー形式を返します。

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Wait 12 seconds, then retry.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 12
  }
}
```

| フィールド                 | 返される条件               | 意味                                                                                                         |
| --------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| `code`                | 常に                   | 下の表のコード。分岐にはこれを使う                                                                                          |
| `message`             | 常に                   | 原因を示す英語の文。`bad_request` では対象フィールドも示す。人とログ向けで、解析に使わない                                                       |
| `retryable`           | 常に                   | 同じ呼び出しが後で成功する可能性があれば `true`（すべての `429`、`500`、`503`）。リクエスト、キー、残高を変更するまで失敗する場合は `false`。`false` の呼び出しをループしない |
| `request_id`          | 常に                   | 保存する。サポートが呼び出しを特定するために使う                                                                                   |
| `retry_after_seconds` | `429`、待機時間が分かる `503` | 待機する秒数。同じ値を `Retry-After` ヘッダーでも返す                                                                         |

テキストエンドポイントは SDK 独自のエラー形式を維持します。[テキストエンドポイント](#text-endpoints)を参照してください。

`POST /v1/moderations` もこの形式を使います。このエンドポイントのみ、エラーに OpenAI の `type` と `param`（常に `null`）を追加し、OpenAI SDK が通常の例外を送出できるようにします。[Moderation API](/moderation) を参照してください。

## 失敗が現れる場所

タスクには 2 つの失敗タイミングがあり、応答も異なります。

1. **作成時。** タスクが存在する前にリクエストが拒否されます。HTTP エラーと `error` オブジェクトが返り、`data.id` はありません。課金されません。
2. **受け付け後。** `POST` は `data.id` を含む `201` を返しています。後で `status: "failed"` となります。`GET /v1/tasks/{task_id}` は引き続き `200` で、失敗は `data.error_code`、`data.error_message`、`data.retryable` に示されます。仮確保したクレジットは返金されます。

```json
{
  "error": {
    "code": "content_policy_violation",
    "message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "retryable": false,
    "request_id": "req_abc123"
  }
}
```

```json
{
  "data": {
    "id": "task_8K2qA",
    "status": "failed",
    "error_code": "content_policy_violation",
    "error_message": "The request was blocked by content moderation. Please change the prompt or the input and try again.",
    "retryable": false
  }
}
```

同じ失敗にはどちらでも同じコードが付き、利用ログのエラー行も同じです（`content_policy_violation: The request was blocked…`）。受け付け済みタスクの終了時のコードは、`content_policy_violation`、`bad_request`、`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed` のいずれかです。その他はリクエスト時の拒否を示します。

## コード一覧

| コード                         | HTTP  | `retryable` | 発生条件                                                                                        | 対処                                                         |
| --------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `bad_request`               | `400` | `false`     | 不正な JSON、未対応のフィールド、値、組み合わせ（サイズ、比率、長さ、数、プロンプト長など）。メッセージでフィールドを示す。入力 URL の取得失敗や処理できないファイルも対象  | フィールドを修正、または公開の到達可能な HTTPS URL と対応形式を使う                    |
| `content_policy_violation`  | `400` | `false`     | プロンプト、入力、生成結果がコンテンツ審査で拒否された                                                                 | プロンプトや入力を変更。同じ内容を再送しない                                     |
| `missing_api_key`           | `401` | `false`     | API キー未送信                                                                                   | `Authorization: Bearer <key>` を送信。`sk-` プレフィックスの有無はどちらでもよい |
| `invalid_api_key`           | `401` | `false`     | キーが不正、期限切れ、無効、上限到達。メッセージに理由を示す。削除したキーは即座に使えなくなる                                             | ダッシュボードで有効なキーを確認、または別のキーへ切り替える                             |
| `insufficient_credits`      | `402` | `false`     | 残高が 0、または料金に不足。キー独自の利用上限が不足する場合もあり、メッセージに示す                                                 | チャージするかキーの上限を増やして再送                                        |
| `forbidden`                 | `403` | `false`     | キーやアカウントに許可されていない。無料クレジット対象外のモデル、IP 許可リスト対象外、キーのモデルグループ対象外など                                | メッセージを確認。無料クレジットのアカウントはチャージで全モデルが利用可能になる                   |
| `not_found`                 | `404` | `false`     | テキスト・機能で不明または料金未設定のモデル、不明な機能、アカウントに存在しないタスク。画像・動画の作成では、カタログにないモデルは代わりに `400 bad_request`    | ID とキーのアカウントを確認。機能では `suggestions` を使う                     |
| `read_request_body_failed`  | `413` | `false`     | 本文が大きすぎて読み取れない                                                                              | 本文を小さくする。大きいファイルはアップロードし URL を渡す                           |
| `idempotency_conflict`      | `409` | `false`     | `Idempotency-Key` を異なる本文で再利用、または同じキーの初回リクエストがまだ処理中                                          | 完全に同じリクエストの場合にのみ再利用                                        |
| `rate_limit_exceeded`       | `429` | `true`      | 無料モデルの上限を含め、キーのリクエスト数が多すぎる。テキストではモデルの処理容量超過（"This model is receiving too many requests"）も示す | `Retry-After`（`retry_after_seconds` も同じ）秒待って再試行            |
| `user_concurrency_exceeded` | `429` | `true`      | 同時に処理するタスクが多すぎる                                                                             | 実行中のタスクの完了を待つ。即座の再試行は許容量を消費するだけ                            |
| `internal_error`            | `500` | `true`      | 予期しない内部エラー                                                                                  | 1 回再試行。続く場合は `request_id` を添えて問い合わせ                        |
| `processing_unavailable`    | `503` | `true`      | BeatAPI 側でモデルが一時的に利用できない、または処理容量不足                                                          | バックオフして後で再試行、または別モデルを使う                                    |
| `processing_timeout`        | `503` | `true`      | 所定の時間内に処理が完了しなかった                                                                           | バックオフして再試行                                                 |
| `processing_failed`         | `503` | `true`      | BeatAPI 側のその他の理由で処理失敗                                                                       | バックオフして再試行                                                 |
| `result_transfer_failed`    | `503` | `true`      | 結果は生成されたが保存できなかった                                                                           | バックオフして再試行                                                 |

`processing_unavailable` と `rate_limit_exceeded` は異なります。`rate_limit_exceeded` は**利用者の**リクエスト頻度を下げる必要がある状態です。`processing_unavailable` は、リクエスト自体は適切でも、モデルが今は処理を受けられない状態です。

BeatAPI 自身は `502` と `504` を返しません。それでも見られる場合は、BeatAPI に到達できなかったネットワークのエッジで発生しており、本文は JSON ではありません。`503` と同様にバックオフして再試行してください。本文が `error code: 1010` の `403` もエッジで発生しています。Python の `urllib` など、クライアントの標準 User-Agent が拒否されたため、`User-Agent` を明示してください。

### Realtime と Webhook のコード

[Realtime](/realtime-api) セッションと [Webhook](/webhooks) の検証にのみ現れます。

| コード                             | HTTP  | `retryable` | 発生条件                         |
| ------------------------------- | ----- | ----------- | ---------------------------- |
| `realtime_disabled`             | `503` | `false`     | アカウントで Realtime が有効でない       |
| `realtime_capacity_unavailable` | `503` | `true`      | Realtime の処理容量が一時的に不足        |
| `realtime_session_expired`      | `410` | `false`     | セッションが使えない。新しく作成する           |
| `origin_not_allowed`            | `403` | `false`     | ブラウザーのオリジンがセッションで許可されていない    |
| `invalid_client_secret`         | `401` | `false`     | セッションのシークレットが不正、または利用できない    |
| `transport_not_allowed`         | `400` | `false`     | 指定したトランスポートが許可されていない         |
| `invalid_signature`             | —     | —           | Webhook の署名またはタイムスタンプを検証できない |

## テキストエンドポイント

`POST /v1/chat/completions`、`POST /v1/responses`、`POST /v1/messages` は SDK 本来のエラー形式を維持し、OpenAI/Anthropic SDK が通常の例外を送出します。本文に `retryable` や `request_id` フィールドはないため、ステータスと下の表で再試行を判断します。

* **OpenAI 形式**（`/v1/chat/completions`、`/v1/responses`）は `{"error":{"message","type","code"}}`。コードは `error.code`、`error.type` は常に `beatapi_error`。リクエスト ID は `(request id: …)` としてメッセージ末尾に付きます。
* **Anthropic 形式**（`/v1/messages`）は `{"type":"error","error":{"type","message"}}`。コードは `error.type` に入ります。

ステータス、コード、英語のメッセージは上記と共通です。

| HTTP  | コード                                                                   | 対処                                                                                 |
| ----- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `400` | `bad_request` / `content_policy_violation`                            | リクエストや入力を修正。変更せず再送しない                                                              |
| `401` | `missing_api_key` / `invalid_api_key`                                 | SDK が送信するキーを確認                                                                     |
| `402` | `insufficient_credits`                                                | チャージする                                                                             |
| `403` | `forbidden` / `access_denied`                                         | `forbidden` は無料クレジットのみの場合などモデルが利用不可。`access_denied` は IP 許可リスト対象外、またはキーのモデルグループ対象外 |
| `404` | `not_found`                                                           | 不明なモデル。`GET /v1/models` で有効なモデルを確認                                                 |
| `413` | `read_request_body_failed`                                            | 本文を小さくする                                                                           |
| `429` | `rate_limit_exceeded`                                                 | 利用上限、またはモデルの処理容量超過。`Retry-After` 秒待つ                                               |
| `500` | `internal_error`                                                      | バックオフして 1 回再試行                                                                     |
| `503` | `processing_unavailable` / `processing_timeout` / `processing_failed` | バックオフして再試行、または別モデルを使う。課金なし                                                         |

## 再試行方針

* **変更せず再試行しない**（`retryable: false`）コードは `bad_request`、`content_policy_violation`、`missing_api_key`、`invalid_api_key`、`insufficient_credits`、`forbidden`、`not_found`、`read_request_body_failed`、`idempotency_conflict`。すべての `400`、`401`、`402`、`403`、`404`、`409`、`413` です。
* **待ってから再試行する**（`retryable: true`）コードは `rate_limit_exceeded` と `user_concurrency_exceeded`。`Retry-After` / `retry_after_seconds` に従うか、実行中タスクの完了を待ちます。
* **バックオフして再試行する**（`retryable: true`）コードは `internal_error` と 4 つの `503` コード。ジッターと上限付きの指数バックオフを使います。失敗したタスクは返金されるため、新しい試行は成功した場合のみ新たに課金されます。再送で 2 つ目のタスクを作らないよう、作成時に `Idempotency-Key` を付けます。

## 変更履歴

* **2026-09-29** — `401` は常に `missing_api_key`（キー未送信）または `invalid_api_key`（不正、期限切れ、無効、上限到達。理由はメッセージに表示）になりました。旧名称 `unauthorized` を古いクライアントで見る場合は `invalid_api_key` と同様に扱います。残高不足はテキストを含む全エンドポイントで `402 insufficient_credits` です。すべてのエラーに `retryable` を付け、`message` は原因を示す英語の文になりました。
* **2026-09-25** — BeatAPI 自身は `502` と `504` を返さなくなりました。処理失敗（`processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed`）はすべて共通 JSON 形式の `503` です。完了できない同期 Social Data/Web 呼び出し、バックグラウンドで失敗した調査（返金）も対象です。エッジの `502` は BeatAPI に到達できなかったもので、本文は JSON ではありません。バックオフして再試行します。
* **2026-09-23** — 受け付け後にパラメーター拒否や入力取得不可で失敗したタスクは、従来の `processing_failed` ではなく `bad_request` を返すようになりました。作成時にモデル独自のステータスをそのまま返さず、審査拒否は常に `400 content_policy_violation`、モデル利用不可は `503 processing_unavailable` です。作成時の残高不足は `402 insufficient_credits` です。