# Error

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

| Field | Arti |
|---|---|
| `type` | Kelas umum error. Tentukan tindakan berdasarkan ini. |
| `code` | Alasan spesifik, stabil, dan dapat dibaca mesin. Setiap kode memiliki bagian di bawah; `doc_url` mengarah ke sana. |
| `message` | Penjelasan yang dapat dibaca manusia, aman untuk dicatat atau ditampilkan kepada pengembang. |
| `param` | Parameter input atau header yang bermasalah, jika ada. |
| `details` | Untuk error input, setiap masalah yang ditemukan: `[{ "param", "message" }]`. |
| `request_id` | Permintaan yang terkait, jika ada. |

Tidak ada biaya untuk panggilan yang mengembalikan error. Permintaan yang gagal *setelah* diterima tetap berstatus
`failed`, membawa `error: { "type", "code", "message" }` pada objek permintaan, dan otomatis menerima pengembalian dana.

## Jenis

| Jenis | Status HTTP | Tindakan |
|---|---|---|
| `invalid_request` | 400, 413 atau 422 | Perbaiki permintaan. Mengulangi panggilan yang sama akan gagal lagi. |
| `authentication_error` | 401 | Kirim kunci yang valid dalam `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Gunakan kunci dengan scope yang diperlukan. |
| `not_found` | 404 | Periksa id model atau id permintaan. |
| `insufficient_credits` | 402 | Isi ulang saldo API (`top_up_url` dalam error). |
| `budget_exceeded` | 402 | Anggaran kunci tersebut telah habis. Final: minta pemilik kunci menaikkannya. |
| `conflict` | 409 | Resource tidak berada dalam status yang memungkinkan panggilan ini. |
| `rate_limited` | 429 | Tunggu `Retry-After` detik, lalu coba lagi. |
| `upstream_error` | 502 | Backend model gagal. Aman untuk mencoba lagi dengan `Idempotency-Key` yang sama: proses akan dijalankan ulang; Anda tidak dikenai biaya. |
| `service_unavailable` | 503 | API dijeda atau dependensi sedang tidak tersedia. Coba lagi nanti. |
| `internal_error` | 500 | Bug di sisi kami. Coba lagi; jika berlanjut, hubungi dukungan dengan waktu kejadian dan `request_id`. |

## Kode

### `invalid_request`

Permintaan umum yang formatnya salah (400).

### `invalid_json`

Body bukan JSON yang valid (400).

### `invalid_body`

Body adalah JSON valid tetapi bukan objek; input model harus berupa objek JSON (400).

### `body_too_large`

Body lebih besar dari 16 MB (413). Unggah file besar dan teruskan URL-nya (lihat [File](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parameter kueri memiliki nilai yang salah, misalnya `limit` di luar 1 hingga 100, `wait` bukan angka, `status` atau
`category` yang tidak dikenal, atau `storage` selain `permanent` / `temporary` (400). `param` menyebutkannya.

### `invalid_category`

`GET /openapi.json?category=` menyebutkan kategori yang tidak ada (400). `GET https://api.doitong.ru/v1/categories` menampilkannya.

### `invalid_cursor`

`cursor` pada panggilan daftar bukan milik daftar ini (400). Mulai lagi tanpa cursor.

### `invalid_idempotency_key`

Header `Idempotency-Key` kosong atau lebih panjang dari 255 karakter (400).

### `invalid_arguments`

Panggilan tool MCP memiliki argumen yang hilang atau formatnya salah (khusus MCP). `param` menyebutkan argumen tersebut.

### `invalid_input`

Input model tidak lolos validasi (422): parameter tidak dikenal (pesan menyarankan nama valid yang paling dekat),
parameter wajib yang hilang, tipe yang salah, nilai di luar daftar atau rentang yang diizinkan, atau nama kanonis dan
nama native diberikan dengan nilai berbeda. `param` adalah parameter bermasalah pertama dan `details` mencantumkan semuanya.
Tidak ada biaya.

### `unsupported_file`

File memiliki tipe yang tidak kami terima (422), misalnya unggahan dengan ekstensi yang tidak didukung, atau `content_type`
yang tidak cocok dengan ekstensi.

### `invalid_webhook_url`

`webhook_url` bukan URL publik `https://` (422). Alamat privat, lokal, dan `http://` biasa ditolak.

### `missing_api_key`

Endpoint memerlukan kunci API tetapi tidak ada yang dikirim (401).

### `invalid_api_key`

Kunci tidak dikenal, dicabut, atau kedaluwarsa (401).

### `insufficient_scope`

Kunci tidak memiliki scope yang diperlukan panggilan ini (403), misalnya `models:run` untuk menjalankan model, atau `models:read` untuk membaca
permintaan dan saldo. Lihat [Autentikasi](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Akun ditutup atau ditangguhkan (403). Kuncinya tidak lagi berfungsi.

### `not_found`

Path tidak ada (404).

### `model_not_found`

Tidak ada model publik dengan id ini (404). Tampilkan model dengan `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Tidak ada permintaan dengan id ini di akun Anda (404). Permintaan dari akun lain tidak pernah terlihat.

### `insufficient_credits`

**Saldo API** akun (kredit API, 1.000 kredit API = $1 — bukan kredit aplikasi Doitong) tidak mencukupi untuk harga panggilan ini (402).
Respons dikirim sebelum biaya apa pun dikenakan. Error membawa `top_up_url`; tambahkan dana di [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) lalu coba 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 melampaui anggaran kunci API dalam kredit API (402). Anggaran ditetapkan oleh pemilik kunci; mencoba lagi tidak
membantu sampai anggaran dinaikkan.

### `conflict`

Panggilan bertentangan dengan status resource saat ini (409).

### `idempotency_mismatch`

`Idempotency-Key` sudah digunakan dengan body yang berbeda (409). Gunakan kunci baru untuk operasi baru.

### `idempotency_in_progress`

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

### `request_active`

Permintaan masih `queued` atau `running`, sehingga belum memiliki file untuk dihapus (409). Hapus file setelah permintaan selesai.

### `not_cancelable`

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

### `rate_limited`

Kunci membuat terlalu banyak permintaan dalam jendela saat ini (429). Lihat header `X-RateLimit-*` dan `Retry-After`.

### `too_many_inflight`

Akun sudah memiliki 10 permintaan `queued` atau `running` (429). Mulai permintaan berikutnya setelah salah satunya selesai.

### `upstream_error`

Backend model menolak atau gagal memproses permintaan (502 saat menjalankan, atau `failed` dengan kode ini pada permintaan). Kredit API dikembalikan.
Jika backend menolak input itu sendiri, panggilan mengembalikan `422 invalid_input` dengan pesannya.

### `upstream_lost`

Backend model tidak lagi mengetahui permintaan tersebut, sehingga hasil tidak akan pernah tiba. Permintaan berakhir sebagai `failed` dengan kode ini
(tipe `upstream_error`) dan dana dikembalikan. Jalankan lagi.

### `timeout`

Permintaan berjalan lebih lama dari batasnya (15 menit untuk gambar, 60 untuk video, 30 lainnya) dan dihentikan. Permintaan berakhir sebagai
`failed` dengan kode ini dan dana dikembalikan.

### `service_unavailable`

API sedang dijeda sementara, atau dependensi seperti unggahan file tidak tersedia (503). Coba lagi nanti.

### `internal_error`

Terjadi masalah di sisi kami (500). Coba lagi; jika berlanjut, hubungi dukungan.

### `charge_failed`

Biaya tidak dapat dibebankan ke akun karena masalah internal (500). Permintaan ditandai `failed`; tidak ada dana yang diambil. Coba lagi.

### `pricing_unavailable`

Harga model belum dikonfigurasi, sehingga saat ini tidak dapat dihitung atau dijalankan (500).