# Kode error

> Arti dan cara menangani semua kode error YesCaptcha API, dikelompokkan menurut format permintaan, akun dan saldo, tugas bersamaan dan jeda, hasil tugas, parameter situs, gambar, proxy, dan server. Permintaan yang mengembalikan error tidak dipotong poinnya.

Source: https://docs.yescaptcha.com/id/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

Saat terjadi error, API mengembalikan `errorId: 1`, `errorCode` berisi kode error, dan `errorDescription` berisi penjelasan teks. Permintaan yang mengembalikan error tidak dipotong poinnya: error saat membuat tugas tidak dipotong, sedangkan tugas yang gagal dikenali atau timeout setelah dibuat poinnya dikembalikan otomatis.

> **Tips:** Di program Anda, tentukan penanganan berdasarkan `errorCode`, jangan berdasarkan teks `errorDescription`, karena teks penjelasan bisa berubah.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## Prinsip penanganan

1.  **Error parameter** (format permintaan, ClientKey, jenis tugas, parameter situs, gambar) tidak akan berubah meski dikirim ulang, jadi perbaiki permintaan terlebih dahulu.
2.  **Kegagalan pengenalan dan timeout** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`) dapat dicoba lagi dengan membuat tugas baru.
3.  Setelah error, **hentikan polling** untuk `taskId` tersebut dan jangan mengirim ulang permintaan yang sama dengan frekuensi tinggi.
4.  Untuk error yang bertanda “dihitung untuk jeda otomatis”, jika satu `clientKey` mengalaminya 100 kali dalam satu menit, pembuatan tugas dijeda selama 5 menit. Error bertanda “cache” tidak dihitung, tetapi selama masa cache, permintaan yang sama langsung mengembalikan error yang sama. Lihat [Batas tugas bersamaan dan jeda otomatis](https://docs.yescaptcha.com/id/api/rate-limits.md).

## Semua kode error

### request

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Ada kolom wajib yang hilang (seperti `clientKey`, atau `websiteURL` / `websiteKey` untuk jenis tugas tersebut), atau isi permintaan bukan JSON | Tambahkan kolom yang hilang sesuai daftar di halaman jenis tugas, dan kirim JSON dengan `POST` serta `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Dihitung untuk jeda) | Isi permintaan bukan JSON yang valid | Buat isi permintaan dengan library JSON, bukan dengan menggabungkan string; JSON tidak boleh berisi komentar `//` |
| `ERROR_TASK_ABSENT` (Dihitung untuk jeda) | Kolom `task` tidak ada pada pemanggilan `createTask` | Letakkan parameter tugas di dalam objek `task`. Dengan Python requests gunakan `json=data`, bukan `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Dihitung untuk jeda) | `task.type` salah eja atau jenis tersebut sudah dihentikan | Salin nama jenis dari "Jenis tugas dan harga"; nama bersifat peka huruf besar/kecil |
| `ERROR_PAGE_NOT_FOUND` | Path yang diminta tidak ada | Periksa URL endpoint, misalnya `https://api.yescaptcha.com/createTask`; nama metode peka huruf besar/kecil |
| `ERROR_BAD_REQUEST` | Permintaan tidak dapat diproses, biasanya karena metode HTTP salah (GET, bukan POST) atau nilai parameter tidak valid | Kirim JSON dengan `POST`, dan periksa tipe serta nilai parameter |
| `ERROR_ILLEGAL_PARAMETERS` | Nilai parameter tidak valid. Umum terjadi pada halaman verifikasi Cloudflare: `websiteURL` bukan URL publik berawalan `http://` / `https://`, `postData` bukan objek, atau `requiredCookies` bukan array string (dikembalikan oleh createTask, tidak ada pemotongan poin); atau domain target tidak dapat di-resolve melalui proxy (dikembalikan oleh getTaskResult, poin dikembalikan secara otomatis) | Perbaiki nilainya sesuai tabel parameter di halaman jenis tugas. Jika domain tidak dapat di-resolve, periksa ejaan URL dan apakah proxy dapat mengakses situs tersebut |

### auth

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Dihitung untuk jeda) | `clientKey` tidak ada: ada karakter yang bertambah atau hilang saat disalin, atau kunci sudah diatur ulang di Dasbor | Salin ulang kunci dari Dasbor yescaptcha.com, tanpa spasi atau baris baru |
| `ERROR_KEY_EXPIRED` (Dihitung untuk jeda) | `clientKey` telah kedaluwarsa (dikembalikan oleh createTask dan getBalance, tidak ada pemotongan poin). Ada dua kemungkinan: tidak digunakan dalam waktu lama sehingga sistem menetapkan waktu kedaluwarsa untuk melindungi akun (pengingat dikirim melalui email sebelum kedaluwarsa), atau masa berlaku yang ditetapkan untuk `clientKey` ini telah lewat | Masuk ke Dasbor yescaptcha.com. Jika kedaluwarsa karena lama tidak digunakan, buat `clientKey` baru; saldo akan otomatis dipindahkan ke `clientKey` yang baru. Jika masa berlaku sudah diatur, ubah masa berlakunya atau gunakan `clientKey` lain. Lalu perbarui program Anda dengan `clientKey` yang baru |
| `ERROR_KEY_IP_NOT_ALLOWED` | `clientKey` ini memiliki allowlist IP, dan IP asal permintaan tidak ada di dalamnya (dikembalikan oleh createTask dan getBalance, tidak ada pemotongan poin, tidak dihitung untuk jeda otomatis) | Masuk ke Dasbor yescaptcha.com, lalu tambahkan IP publik mesin yang mengirim permintaan ke allowlist `clientKey` ini, atau gunakan `clientKey` lain. Jika beberapa mesin memanggil API, tambahkan IP publik masing-masing (ini adalah IP yang memanggil API YesCaptcha, bukan proxy di parameter tugas) |
| `ERROR_KEY_QUOTA_EXCEEDED` | `clientKey` ini memiliki batas pengeluaran, dan sisa batas untuk periode saat ini kurang dari biaya tugas ini (dikembalikan oleh createTask, tidak ada pemotongan poin, tidak dihitung untuk jeda otomatis). Batas dihitung dari poin yang benar-benar dipotong; poin yang dikembalikan untuk tugas yang gagal atau timeout akan kembali ke batas | Masuk ke Dasbor yescaptcha.com lalu naikkan batas `clientKey` ini, tunggu periode berikutnya (direset setiap hari, setiap Senin, atau setiap tanggal 1 tiap bulan, waktu Beijing; batas sekali pakai tidak direset), atau gunakan `clientKey` lain. `getBalance` mengembalikan sisa batas `clientKey` ini (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Saldo tidak cukup. Saldo harus di atas 10 poin untuk membuat tugas | Isi saldo lalu coba lagi. Gunakan `getBalance` untuk memeriksa saldo |

### limit

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Kadang dihitung untuk jeda) | Terlalu banyak tugas jenis ini yang sedang diproses untuk akun tersebut. `limit` pada respons adalah batas saat ini. Permintaan tidak diproses dan tidak ada pemotongan poin | Tunggu permintaan yang sedang berjalan selesai, atau tunggu 1–2 detik lalu coba lagi; batasi jumlah permintaan yang menunggu hasil secara bersamaan |
| `ERROR_IP_BLOCKED_5MIN` | `clientKey` ini menghasilkan terlalu banyak error dalam waktu singkat dan dijeda secara otomatis. `retryAfter` adalah sisa detik dan `blockReason` adalah error yang menyebabkannya | Perbaiki permintaan sesuai `blockReason` dan tunggu `retryAfter` detik; mengirim permintaan selama jeda tidak memperpanjangnya |
| `ERROR_NO_SLOT_AVAILABLE` | Layanan pengenalan sedang kelebihan beban untuk sementara. Jika dikembalikan oleh createTask, tidak ada poin yang dipotong; tugas yang menunggu terlalu lama dalam antrean juga mengembalikannya dari getTaskResult, dan poinnya dikembalikan secara otomatis | Tunggu beberapa detik, lalu buat tugas lagi |

### task

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Dihitung untuk jeda) | `taskId` tidak ada, sudah kedaluwarsa (hasil disimpan sekitar 10 menit), milik `clientKey` lain, atau dibuat di endpoint yang lain | Hentikan polling untuk tugas ini. Lakukan query dengan endpoint dan `clientKey` yang sama dengan yang digunakan untuk membuatnya |
| `ERROR_TASK_TIMEOUT` | Tugas tidak selesai dalam waktu yang ditentukan (biasanya 110 detik); poin dikembalikan secara otomatis | Buat tugas baru; jika terus timeout, coba jenis tugas lain untuk captcha yang sama |
| `ERROR_CAPTCHA_UNSOLVABLE` | Captcha tidak berhasil dikenali kali ini; poin dikembalikan. Error ini tidak dihitung untuk jeda otomatis | Buat tugas baru. Jika terus gagal, periksa `websiteURL`, `websiteKey`, dan parameter lainnya, atau coba jenis tugas lain untuk captcha yang sama |
| `ERROR_SETTLEMENT_FAILED` (Dihitung untuk jeda) | Saldo tidak cukup saat penyelesaian, sehingga hasil tidak dikembalikan | Isi saldo, lalu buat tugas baru |
| `ERROR_NO_SUCH_CAPCHA_ID` | Tugas sudah tidak berlaku | Hentikan polling untuk tugas ini dan buat tugas baru |
| `ERROR_RECAPTCHA_TIMEOUT` | Pengenalan captcha melewati batas waktu; poin dikembalikan | Buat tugas baru |

### site

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Di-cache, tidak memicu jeda) | `websiteKey` tidak valid | Cari sitekey di halaman sekali lagi (lihat panduan mencari parameter). Permintaan yang identik akan langsung mengembalikan error ini selama masa cache, dengan `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Di-cache, tidak memicu jeda) | Domain pada `websiteURL` tidak cocok dengan `websiteKey` | Isi `websiteURL` dengan alamat halaman yang menampilkan captcha |
| `ERROR_INVALID_KEY_TYPE` (Di-cache, tidak memicu jeda) | Sitekey milik jenis captcha yang berbeda, misalnya key v3 dipakai pada jenis tugas v2 | Tentukan dulu jenis captcha-nya (lihat "Mengenali jenis captcha"), lalu pilih jenis tugas yang sesuai; untuk v2 invisible, setel `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Di-cache, tidak memicu jeda) | Situs ini belum didukung | Coba jenis tugas lain untuk captcha yang sama, atau hubungi dukungan |
| `ERROR_HIGH_DEMAND_DOMAIN` (Dihitung untuk jeda) | Situs ini belum didukung | Berhenti mengirim tugas untuk situs ini dan hubungi dukungan |
| `ERROR_FAILED_LOADING_WIDGET` | Captcha tidak dapat dimuat dengan parameter yang diberikan | Periksa `websiteURL` dan `websiteKey`; untuk jenis tugas dengan proxy sendiri, periksa apakah proxy dapat mengakses situs tersebut |

### image

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Dihitung untuk jeda) | Gambar kosong atau terlalu kecil | Pastikan data Base64 lengkap dan tidak memakai awalan `data:image/...;base64,` |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Dihitung untuk jeda) | Gambar terlalu besar | Kompres atau perkecil gambar; seluruh body permintaan tidak boleh melebihi 6 MB |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Dihitung untuk jeda) | Format gambar tidak didukung, atau gambar bukan jenis yang dapat ditangani oleh jenis tugas ini. Satu kali kejadian menyebabkan jeda 30 menit | Gunakan JPG atau PNG dan pastikan gambar sesuai dengan jenis tugas, misalnya pengenalan gambar reCAPTCHA memerlukan 100x100, 300x300, atau 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Dihitung untuk jeda) | Ukuran gambar tidak memenuhi persyaratan jenis tugas ini | Ubah ukuran gambar sesuai penjelasan di halaman jenis tugas |
| `ERROR_PARSE_IMAGE_FAIL` | Gambar tidak dapat didekode, biasanya karena Base64 terpotong atau memakai awalan | Periksa encoding Base64, lalu hapus awalan `data:` dan jeda baris |
| `ERROR_UNKNOWN_QUESTION` | `question` salah, atau pertanyaan ini belum didukung | Cocokkan dengan daftar pertanyaan di halaman jenis tugas. Untuk pertanyaan yang belum didukung, hubungi dukungan; pertanyaan baru biasanya didukung dalam 3 hari kerja |
| `ERROR_UNKNOW_450x450_QUESTION` | Pertanyaan ini belum didukung untuk gambar 4x4 (450x450) | Muat ulang tantangan di halaman untuk mendapatkan pertanyaan lain |

### proxy

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Proxy menolak koneksi | Periksa alamat, port, dan protokol proxy, serta pastikan proxy menerima koneksi eksternal (bukan alamat lokal seperti 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Koneksi ke proxy melewati batas waktu | Gunakan proxy yang lebih stabil |
| `ERROR_PROXY_READ_TIMEOUT` | Pembacaan data melalui proxy melewati batas waktu | Gunakan proxy yang lebih cepat |
| `ERROR_PROXY_BANNED` | Proxy tidak tersedia, atau IP-nya diblokir oleh situs target | Gunakan proxy lain |
| `ERROR_PROXY_INCORRECT` | Format parameter proxy salah | Periksa format `proxyType`, `proxyAddress`, `proxyPort` (atau string `proxy`) |
| `ERROR_PROXY_TRANSPARENT` | Proxy bersifat transparan dan mengungkap IP asli | Gunakan proxy anonim (elite) |
| `ERROR_PROXY_NOT_AUTHORISED` | Username atau kata sandi proxy salah | Periksa `proxyLogin` dan `proxyPassword` (atau kredensial di string `proxy`) |
| `ERROR_PROXY_TLS_ERROR` | TLS handshake dengan proxy gagal, biasanya karena `proxyType` salah (misalnya https disetel untuk proxy http) | Periksa protokol proxy |
| `ERROR_PROXY_CONNECTION_FAILED` | Tidak dapat terhubung ke server proxy | Periksa alamat dan port proxy, lalu pastikan proxy berfungsi dengan baik |

### server

| Kode error | Arti | Yang perlu dilakukan |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Layanan sedang tidak tersedia untuk sementara (kode ini memang dieja `UNAVALIABLE`) | Coba lagi nanti; hubungi dukungan jika terus terjadi |
| `ERROR_INTERNAL_SERVER_ERROR` | Terjadi error internal pada server | Coba lagi nanti; jika terus terjadi, hubungi dukungan dan sertakan `taskId` |
| `ERROR_UNKNOWN` | Error yang belum terklasifikasi | Coba lagi nanti; jika terus terjadi, hubungi dukungan dan sertakan `taskId` |

## Field tambahan

Sebagian respons error memuat field tambahan:

| Field | Muncul pada | Keterangan |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, error yang di-cache | Sisa waktu tunggu dalam detik |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Kode error yang memicu jeda |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Jenis, URL, dan sitekey dari permintaan yang memicu jeda, untuk memudahkan pelacakan |
| `cached` | Error yang di-cache | Bernilai `true` berarti ini hasil dari cache dan tidak ada pengenalan yang sebenarnya |
| `badRequest` | Error yang di-cache | Parameter yang terkena cache |
| `limit` | `ERROR_THREADS_MAXIMUM` | Batas tugas bersamaan Anda saat ini |

Aturan bahasa `errorDescription` dapat dilihat di [Permintaan dan respons](https://docs.yescaptcha.com/id/api/overview.md).