Kode error

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.

{
  "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.

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.