エラー

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

エラーオブジェクト

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

{
  "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 独自のエラー形式を維持します。テキストエンドポイントを参照してください。

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

失敗が現れる場所

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

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

{
  "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"
  }
}

{
  "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 セッションと Webhook の検証にのみ現れます。

コード	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 です。