# Ralat

Setiap endpoint gagal dengan cara yang sama: status HTTP dan satu sampul 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"
  }
}
```

| Medan | Maksud |
|---|---|
| `type` | Kelas umum ralat. Tentukan tindakan berdasarkan ini. |
| `code` | Sebab tepat, stabil dan boleh dibaca mesin. Setiap kod mempunyai bahagian di bawah; `doc_url` memaut kepadanya. |
| `message` | Penjelasan yang boleh difahami manusia, selamat untuk dilog atau dipaparkan kepada pembangun. |
| `param` | Parameter input atau pengepala yang bermasalah, jika ada. |
| `details` | Untuk ralat input, setiap masalah yang ditemui: `[{ "param", "message" }]`. |
| `request_id` | Permintaan yang berkaitan, jika ada. |

Tiada caj dikenakan untuk panggilan yang mengembalikan ralat. Permintaan yang gagal *selepas* diterima mengekalkan status
`failed`, membawa `error: { "type", "code", "message" }` pada objek permintaan dan bayaran balik dibuat secara automatik.

## Jenis

| Jenis | Status HTTP | Tindakan |
|---|---|---|
| `invalid_request` | 400, 413 atau 422 | Betulkan permintaan. Percubaan semula panggilan yang sama akan gagal lagi. |
| `authentication_error` | 401 | Hantar kunci yang sah dalam `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Gunakan kunci dengan skop yang diperlukan. |
| `not_found` | 404 | Semak id model atau id permintaan. |
| `insufficient_credits` | 402 | Tambah nilai baki API (`top_up_url` dalam ralat). |
| `budget_exceeded` | 402 | Belanjawan kunci itu sendiri telah habis digunakan. Akhirnya: minta pemilik kunci menaikkannya. |
| `conflict` | 409 | Sumber tidak berada dalam keadaan yang membenarkan panggilan ini. |
| `rate_limited` | 429 | Tunggu `Retry-After` saat, kemudian cuba lagi. |
| `upstream_error` | 502 | Backend model gagal. Selamat untuk mencuba semula dengan `Idempotency-Key` yang sama: ia dijalankan semula; anda tidak dicaj. |
| `service_unavailable` | 503 | API dijeda atau kebergantungan tidak tersedia. Cuba lagi kemudian. |
| `internal_error` | 500 | Pepijat kami. Cuba lagi; jika berterusan, hubungi sokongan dengan masa dan `request_id`. |

## Kod

### `invalid_request`

Permintaan umum yang tidak diformat dengan betul (400).

### `invalid_json`

Isi kandungan bukan JSON yang sah (400).

### `invalid_body`

Isi kandungan ialah JSON yang sah tetapi bukan objek; input model mestilah objek JSON (400).

### `body_too_large`

Isi kandungan lebih besar daripada 16 MB (413). Muat naik fail besar dan hantar URLnya sebagai ganti (lihat [Fail](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parameter pertanyaan mempunyai nilai yang salah, contohnya `limit` di luar julat 1 hingga 100, `wait` bukan nombor, `status` atau `category` yang tidak diketahui, atau `storage` selain `permanent` / `temporary` (400). `param` menamakannya.

### `invalid_category`

`GET /openapi.json?category=` menamakan kategori yang tidak wujud (400). `GET https://api.doitong.ru/v1/categories` menyenaraikannya.

### `invalid_cursor`

`cursor` bagi panggilan senarai bukan milik senarai ini (400). Mulakan semula tanpa kursor.

### `invalid_idempotency_key`

Pengepala `Idempotency-Key` kosong atau lebih panjang daripada 255 aksara (400).

### `invalid_arguments`

Panggilan alat MCP mempunyai argumen yang hilang atau tidak diformat dengan betul (MCP sahaja). `param` menamakan argumen tersebut.

### `invalid_input`

Input model tidak lulus pengesahan (422): parameter tidak diketahui (mesej mencadangkan nama sah yang paling hampir), parameter wajib yang hilang, jenis yang salah, nilai di luar senarai atau julat yang dibenarkan, atau kedua-dua nama kanonik dan nama asli diberikan dengan nilai berbeza. `param` ialah parameter pertama yang bermasalah dan `details` menyenaraikan kesemuanya.
Tiada caj dikenakan.

### `unsupported_file`

Fail mempunyai jenis yang tidak kami terima (422), contohnya muat naik dengan sambungan yang tidak disokong atau `content_type` yang tidak sepadan dengan sambungan.

### `invalid_webhook_url`

`webhook_url` bukan URL awam `https://` (422). Alamat peribadi, setempat dan `http://` biasa ditolak.

### `missing_api_key`

Endpoint memerlukan kunci API tetapi tiada kunci dihantar (401).

### `invalid_api_key`

Kunci tidak diketahui, dibatalkan atau tamat tempoh (401).

### `insufficient_scope`

Kunci tidak mempunyai skop yang diperlukan oleh panggilan ini (403), contohnya `models:run` untuk menjalankan model atau `models:read` untuk membaca permintaan dan baki. Lihat [Pengesahan](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Akaun ditutup atau digantung (403). Kuncinya tidak lagi berfungsi.

### `not_found`

Laluan tidak wujud (404).

### `model_not_found`

Tiada model awam dengan id ini (404). Senaraikan model dengan `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Tiada permintaan dengan id ini dalam akaun anda (404). Permintaan akaun lain tidak pernah kelihatan.

### `insufficient_credits`

**Baki API** akaun (kredit API, 1,000 kredit API = $1 — bukan kredit aplikasi Doitong) tidak mencukupi untuk menampung harga panggilan ini (402). Respons dihantar sebelum sebarang caj dikenakan. Ralat membawa `top_up_url`; tambah wang di [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) dan cuba lagi.

```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.ru/developers/dashboard#balance",
             "top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

Panggilan ini akan melebihi belanjawan kunci API sendiri dalam kredit API (402). Belanjawan ditetapkan oleh pemilik kunci; percubaan semula tidak membantu sehingga pemilik menaikkannya.

### `conflict`

Panggilan bercanggah dengan keadaan semasa sumber (409).

### `idempotency_mismatch`

`Idempotency-Key` telah digunakan dengan isi kandungan yang berbeza (409). Gunakan kunci baharu untuk operasi baharu.

### `idempotency_in_progress`

Permintaan dengan `Idempotency-Key` yang sama sedang dibuat sekarang (409). Cuba lagi sebentar untuk mendapatkannya.

### `request_active`

Permintaan masih `queued` atau `running`, jadi belum ada fail untuk dipadam (409). Padamkannya selepas selesai.

### `not_cancelable`

Permintaan sudah `succeeded` atau `failed` dan tidak boleh dibatalkan (409).

### `rate_limited`

Kunci membuat terlalu banyak permintaan dalam tetingkap semasa (429). Lihat pengepala `X-RateLimit-*` dan `Retry-After`.

### `too_many_inflight`

Akaun sudah mempunyai 10 permintaan `queued` atau `running` (429). Mulakan permintaan seterusnya apabila salah satu daripadanya selesai.

### `upstream_error`

Backend model menolak atau gagal memproses permintaan (502 semasa menjalankan model, atau `failed` dengan kod ini pada permintaan). Kredit API dibayar balik. Jika backend sendiri menolak input, panggilan mengembalikan `422 invalid_input` dengan mesejnya.

### `upstream_lost`

Backend model tidak lagi mengetahui permintaan itu, jadi keputusan tidak akan tiba. Permintaan berakhir sebagai `failed` dengan kod ini (jenis `upstream_error`) dan bayaran balik dibuat. Jalankan semula.

### `timeout`

Permintaan berjalan melebihi hadnya (15 minit untuk imej, 60 untuk video, 30 untuk yang lain) lalu dihentikan. Permintaan berakhir sebagai `failed` dengan kod ini dan bayaran balik dibuat.

### `service_unavailable`

API dijeda buat sementara atau kebergantungan seperti muat naik fail tidak tersedia (503). Cuba lagi kemudian.

### `internal_error`

Sesuatu rosak di pihak kami (500). Cuba lagi; jika berterusan, hubungi sokongan.

### `charge_failed`

Akaun tidak dapat dicaj kerana masalah dalaman (500). Permintaan ditandakan `failed`; tiada wang diambil. Cuba lagi.

### `pricing_unavailable`

Harga model belum dikonfigurasi, jadi harga tidak dapat diberikan atau model tidak dapat dijalankan sekarang (500).