# エラー

すべてのエンドポイントは同じ方法で失敗します。HTTPステータスと1つのJSONエンベロープが返されます。

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| フィールド | 意味 |
|---|---|
| `type` | エラーの大まかな分類。これに基づいて処理を決めます。 |
| `code` | 正確な理由。安定しており、機械で読み取れます。各コードには以下にセクションがあり、`doc_url`から移動できます。 |
| `message` | 人間が読める説明。ログへの記録や開発者への表示に安全です。 |
| `param` | 問題のある入力パラメータまたはヘッダー（存在する場合）。 |
| `details` | 入力エラーの場合に見つかったすべての問題：`[{ "param", "message" }]`。 |
| `request_id` | 対象となるリクエスト（存在する場合）。 |

エラーを返す呼び出しには何も課金されません。受理された*後*に失敗したリクエストはステータスが
`failed`のままとなり、リクエストオブジェクトに`error: { "type", "code", "message" }`が含まれ、自動的に返金されます。

## 種類

| 種類 | HTTPステータス | 対処方法 |
|---|---|---|
| `invalid_request` | 400、413 または 422 | リクエストを修正します。同じ呼び出しを再試行しても再び失敗します。 |
| `authentication_error` | 401 | `Authorization: Bearer <key>`に有効なキーを指定します。 |
| `permission_error` | 403 | 必要なスコープを持つキーを使用します。 |
| `not_found` | 404 | モデルIDまたはリクエストIDを確認します。 |
| `insufficient_credits` | 402 | API残高をチャージします（エラー内の`top_up_url`）。 |
| `budget_exceeded` | 402 | キー固有の予算を使い切っています。最終的にはキー所有者に引き上げを依頼してください。 |
| `conflict` | 409 | リソースがこの呼び出しを許可する状態ではありません。 |
| `rate_limited` | 429 | `Retry-After`秒待ってから再試行します。 |
| `upstream_error` | 502 | モデルのバックエンドが失敗しました。同じ`Idempotency-Key`で安全に再試行できます。再実行され、課金されていません。 |
| `service_unavailable` | 503 | APIが一時停止中か、依存サービスが停止しています。後で再試行します。 |
| `internal_error` | 500 | 当社側のバグです。再試行し、解消しなければ時刻と`request_id`を添えてサポートへ連絡してください。 |

## コード

### `invalid_request`

形式が正しくない一般的なリクエスト（400）。

### `invalid_json`

本文が有効なJSONではありません（400）。

### `invalid_body`

本文は有効なJSONですがオブジェクトではありません。モデル入力はJSONオブジェクトである必要があります（400）。

### `body_too_large`

本文が16 MBを超えています（413）。大きなファイルをアップロードし、代わりにそのURLを渡してください（[ファイル](https://doitong.com/developers/docs/files)を参照）。

### `invalid_parameter`

クエリパラメータの値が正しくありません。たとえば、`limit`が1～100の範囲外、`wait`が数値でない、未知の
`status`または`category`、あるいは`storage`が`permanent`/`temporary`以外の場合です（400）。`param`に名前が示されます。

### `invalid_category`

`GET /openapi.json?category=`で存在しないカテゴリを指定しています（400）。`GET https://api.doitong.com/v1/categories`で一覧を取得できます。

### `invalid_cursor`

一覧取得呼び出しの`cursor`がこの一覧に属していません（400）。カーソルなしで最初からやり直してください。

### `invalid_idempotency_key`

`Idempotency-Key`ヘッダーが空か、255文字を超えています（400）。

### `invalid_arguments`

MCPツール呼び出しの引数が欠落しているか、形式が正しくありません（MCPのみ）。`param`に引数名が示されます。

### `invalid_input`

モデル入力が検証に通りません（422）。未知のパラメータ（メッセージに最も近い有効な名前が示されます）、
必須パラメータの欠落、型の誤り、許可された一覧または範囲外の値、あるいは正規名とネイティブ名の両方が異なる値で指定されています。
`param`は最初に問題があるパラメータで、`details`にすべての問題が一覧されます。課金はありません。

### `unsupported_file`

受け付けられない種類のファイルです（422）。たとえば、対応していない拡張子のアップロードや、拡張子と一致しない`content_type`です。

### `invalid_webhook_url`

`webhook_url`が公開された`https://` URLではありません（422）。プライベート、ローカル、平文の`http://`アドレスは拒否されます。

### `missing_api_key`

エンドポイントにはAPIキーが必要ですが、送信されていません（401）。

### `invalid_api_key`

キーが不明、無効化済み、または期限切れです（401）。

### `insufficient_scope`

キーにこの呼び出しで必要なスコープがありません（403）。たとえば実行には`models:run`、リクエストと残高の読み取りには`models:read`が必要です。
[認証](https://doitong.com/developers/docs/authentication#scopes)を参照してください。

### `account_disabled`

アカウントが閉鎖または停止されています（403）。そのキーは使用できません。

### `not_found`

パスが存在しません（404）。

### `model_not_found`

このIDの公開モデルはありません（404）。`GET https://api.doitong.com/v1/models`でモデルを一覧表示できます。

### `request_not_found`

このIDのリクエストはアカウントに存在しません（404）。他のアカウントのリクエストは決して表示されません。

### `insufficient_credits`

アカウントの**API残高**（APIクレジット、1,000 APIクレジット = $1。Doitongアプリのクレジットではありません）では、この呼び出しの料金を賄えません（402）。
課金前にレスポンスが送信されます。エラーには`top_up_url`が含まれます。[https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance)で入金して再試行してください。

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

呼び出しによりAPIキー固有のAPIクレジット予算を超過します（402）。予算はキー所有者が設定します。所有者が引き上げるまで再試行しても解決しません。

### `conflict`

呼び出しがリソースの現在の状態と競合しています（409）。

### `idempotency_mismatch`

`Idempotency-Key`は異なる本文ですでに使用されています（409）。新しい操作には新しいキーを使用してください。

### `idempotency_in_progress`

同じ`Idempotency-Key`のリクエストを現在作成中です（409）。少し待って再試行すると取得できます。

### `request_active`

リクエストはまだ`queued`または`running`のため、削除するファイルがありません（409）。完了後に削除してください。

### `not_cancelable`

リクエストはすでに`succeeded`または`failed`で、キャンセルできません（409）。

### `rate_limited`

現在の期間内にキーが多すぎるリクエストを送信しました（429）。`X-RateLimit-*`および`Retry-After`ヘッダーを確認してください。

### `too_many_inflight`

アカウントにはすでに10件の`queued`または`running`リクエストがあります（429）。いずれかが完了してから次を開始してください。

### `upstream_error`

モデルのバックエンドがリクエストを拒否または処理に失敗しました（実行時は502、またはリクエスト上ではこのコードの`failed`）。APIクレジットは返金されます。
バックエンド自体が入力を拒否した場合は、代わりにメッセージ付きの`422 invalid_input`が返ります。

### `upstream_lost`

モデルのバックエンドがリクエストを認識しなくなったため、結果は届きません。このコード（種類は`upstream_error`）で`failed`になり、返金されます。もう一度実行してください。

### `timeout`

リクエストが制限時間（画像は15分、動画は60分、それ以外は30分）を超えて実行され、停止されました。このコードで`failed`になり、返金されます。

### `service_unavailable`

APIが一時停止中か、ファイルアップロードなどの依存サービスが停止しています（503）。後で再試行してください。

### `internal_error`

当社側で問題が発生しました（500）。再試行し、解消しなければサポートへ連絡してください。

### `charge_failed`

内部問題によりアカウントに課金できませんでした（500）。リクエストは`failed`になり、何も引き落とされません。再試行してください。

### `pricing_unavailable`

モデルの価格が設定されていないため、現在は価格の提示も実行もできません（500）。