> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidgen.id/llms.txt
> Use this file to discover all available pages before exploring further.

# Kode error

> Setiap status HTTP yang dikembalikan Vidgen API, pesan aslinya, dan apa yang harus kamu lakukan.

Semua kegagalan memakai body `{ "error": "..." }`. Field diagnostik tambahan hanya muncul di beberapa kode.

> [accordion] 400 — permintaan ditolak
>
> Tubuh permintaan tidak bisa dibaca atau tidak lolos validasi. Job tidak dibuat, kredit tidak terpotong.
>
> | Pesan | Penyebab |
> | - | - |
> | `Body permintaan harus berupa JSON yang valid.` | Salah serialisasi, `Content-Type` tidak cocok, atau body kosong. |
> | `Prompt tidak boleh kosong.` | `prompt` kosong pada model non-motion. |
> | `Model "..." tidak ditemukan.` | Id model salah tulis, atau model sudah dipensiunkan. |
> | `Parameter tidak valid: ...` | Nilai `duration`/`resolution`/`ratio` tidak ada di `capabilities` model. Body ikut mengirim array `fields`. |
> | `Maksimal N gambar referensi.` | Jumlah referensi melebihi batas model. |
> | `Model gambar hanya mendukung referensi gambar (maksimal N gambar).` | Kirim video/audio ke model image. |
> | `Gagal mengunduh media referensi dari URL: ... (HTTP ...)` | URL referensi tidak bisa diambil server (403, 404, atau timeout). |
> | `Durasi Video referensi (...) di luar batas (2-15 detik).` | Referensi terlalu pendek atau terlalu panjang untuk jalur ini. |
> | `Resolusi video ... terlalu kecil untuk video referensi.` | Di bawah 300.000 piksel total atau sisi terpendek \< 360 px. |
> | `Durasi video referensi tidak bisa dibaca. Ekspor videonya sebagai MP4 (bukan WebM) lalu unggah ulang.` | Metadata durasi tidak terbaca pada model motion. |
> | `Permintaan harus berupa multipart/form-data dengan field "file".` | Upload dikirim sebagai JSON. |
> | `Field "file" wajib diisi dengan berkas media.` | Nama field form salah. |
> | `Format berkas tidak valid. ...` | Isi berkas bukan JPG/PNG/WebP/MP4/WebM/MP3/WAV. |
>
> > [!TIP]
> >
> > Untuk error `Parameter tidak valid`, jangan coba-coba nilai lain. Ambil ulang `GET /api/v1/models` dan pakai array yang tercantum.

> [accordion] 401 — autentikasi gagal
>
> | Pesan | Penyebab |
> | - | - |
> | `Header Authorization (Bearer vg_...) atau x-api-key diperlukan.` | Tidak ada header kredensial. |
> | `Format API Key tidak valid. API Key Vidgen harus diawali dengan "vg_".` | Prefix hilang, atau key milik layanan lain. |
> | `API Key tidak valid atau telah dicabut.` | Key salah ketik atau sudah dihapus dari akun. |
> | `Pengguna pemilik API Key tidak ditemukan.` | Akun pemilik key sudah dihapus. |
>
> Jangan pernah mengulang request `401`. Perbaiki kredensialnya lebih dulu.

> [accordion] 402 — kredit tidak cukup
>
> ```json theme={null} theme={null}
> {
>   "error": "Kredit akun tidak mencukupi. Pembuatan ini membutuhkan 10 kredit",
>   "requiredCredits": 10,
>   "currentCredits": 4
> }
> ```
>
> Solusinya adalah top-up, bukan retry. Bandingkan `requiredCredits` dengan harga perkiraan dari katalog sebelum mengirim batch.

> [accordion] 403 — bukan job-mu
>
> ```json theme={null} theme={null}
> { "error": "Akses ditolak: Job ini bukan milik akun Anda." }
> ```
>
> Terjadi ketika `GET /api/v1/jobs/{id}` memakai id milik akun lain — biasanya karena id dihardcode atau key yang dipakai berganti. Job milik sendiri tidak pernah kena kode ini.

> [accordion] 409 — model tidak tersedia
>
> ```json theme={null} theme={null}
> { "error": "Model \"...\" sedang tidak tersedia. Pilih model lain." }
> ```
>
> Modelnya dikenal tapi sedang dimatikan. Segarkan katalog dan pindahkan permintaan ke model lain; jangan diulang ke model yang sama.

> [accordion] 413 — berkas terlalu besar
>
> ```json theme={null} theme={null}
> { "error": "Ukuran berkas melebihi batas maksimal 100 MB." }
> ```
>
> Kompres atau potong dulu. Batas ini berlaku sebelum isi berkas diperiksa, jadi tidak bisa dinegosiasikan lewat parameter.

> [accordion] 429 — kapasitas
>
> Tiga sebab berbeda, bentuk body berbeda:
>
> **Konkurensi penuh (akun Unlimited)**
>
> ```json theme={null} theme={null}
> {
>   "error": "Maksimal 2 proses generate bersamaan. Tunggu salah satunya selesai sebelum memulai yang baru.",
>   "maxConcurrent": 2,
>   "activeJobs": 2
> }
> ```
>
> **Kuota video harian habis**
>
> ```json theme={null} theme={null}
> {
>   "error": "Batas harian tercapai, kuota harian direset pukul 00:00 WIB.",
>   "dailyLimitReached": true,
>   "dailyVideosUsed": 50,
>   "resetsAt": "00:00 WIB"
> }
> ```
>
> **Antrean server penuh / unggahan terlalu sering**
>
> ```json theme={null} theme={null}
> { "error": "Antrean penuh. Silakan coba sesaat lagi." }
> ```
>
> Pada `POST /api/v1/upload`, respons membawa header `Retry-After` dalam detik. Hormati nilainya.
>
> > [!WARNING]
> >
> > `429` berarti tunggu, bukan ganti key. Membuat API key baru tidak menaikkan batas apa pun karena semua batas menempel di akun.

> [accordion] 500 — kegagalan di sisi Vidgen
>
> ```json theme={null} theme={null}
> { "error": "Gagal memuat katalog model." }
> ```
>
> Jarang, dan tidak memakan kredit. Laporkan beserta waktu dan endpoint-nya.

> [accordion] 503 — tidak bisa diproses sekarang
>
> | Pesan | Penyebab |
> | - | - |
> | `Vidgen sedang dalam pemeliharaan. Penggunaan API key dinonaktifkan sementara.` | Situs ditutup sementara; semua key ikut ditolak. |
> | `Layanan autentikasi API Key sedang tidak tersedia.` | Layanan sesi sedang bermasalah. |
> | `Layanan kredit tidak dapat diakses saat ini. Silakan coba sesaat lagi.` | Saldo tidak bisa dibaca, jadi tidak ada kredit yang dipotong. |
> | `Gagal membuat antrean pemrosesan job. Kredit telah dikembalikan.` | Job gagal disimpan; refund sudah dijalankan. |
>
> Gunakan backoff eksponensial dan pertahankan `idempotencyKey` yang sama.

## Kesalahan yang muncul sebagai `failed`, bukan status HTTP

Kasus ini datang belakangan, dari `errorMessage` di [`GET /api/v1/jobs/{id}`](https://docs.vidgen.id/api-reference/get-job). Kredit sudah dipotong lalu dikembalikan, jadi periksa `creditsCharged` yang tersisa `0`.

| Pesan | Artinya |
| - | - |
| `Prompt or reference content triggered AI safety filters ...` | Konten kena filter keamanan. Revisi prompt atau referensi. |
| `Reference video duration is not supported by this model. ...` | Durasi referensi di luar aturan model motion. |
| `Failed to align character with video motion ...` | Wajah/gerakan pada referensi tidak terdeteksi cocok. |
| `This model is temporarily unavailable on our side. ...` | Gangguan sementara di sisi Vidgen. Coba lagi atau ganti model. |
| `The processing service is temporarily undergoing maintenance. ...` | Kapasitas sedang diperbaiki. Tunda, jangan salahkan pengguna. |
| `Queue temporarily throttled due to repeated submission of high-risk content. ...` | Terlalu banyak konten berisiko tinggi dari akun ini. Tunggu 1-2 menit. |

> [!NOTE]
>
> Pesan `errorMessage` sengaja berbahasa Inggris di respons API. Silakan diterjemahkan ke bahasa UI kamu, tapi jangan diubah artinya saat ditampilkan ke pengguna akhir.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.