# Permintaan dan respons

> Ketentuan umum YesCaptcha API: POST JSON, autentikasi dengan ClientKey, format respons errorId, tugas sinkron dan asinkron, polling setiap 5 detik, batas waktu 110 detik, hasil disimpan sekitar 10 menit, bahasa pesan mengikuti Accept-Language.

Source: https://docs.yescaptcha.com/id/api/overview/ · 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/overview/

Semua method menggunakan HTTPS `POST` dengan body JSON (hanya `/useragent` yang `GET`), diautentikasi dengan `clientKey` di body, dan mengembalikan JSON: `errorId` bernilai 0 berarti berhasil, 1 berarti gagal dan disertai `errorCode`. Menyelesaikan satu captcha terdiri dari dua langkah: `createTask` membuat tugas, lalu `getTaskResult` dipanggil setiap 5 detik untuk memeriksa hasil. Jenis sinkron langsung mengembalikan hasil di `createTask`.

## Permintaan

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```

-   Endpoint: `https://api.yescaptcha.com` (global) atau `https://cn.yescaptcha.com` (Tiongkok), lihat [Alamat akses](https://docs.yescaptcha.com/id/getting-started/endpoints.md).
-   Body berupa JSON, dikirim dengan header `Content-Type: application/json`, maksimal 6 MB. JSON tidak boleh berisi komentar.
-   Setiap permintaan harus menyertakan `clientKey`, salin lengkap sesuai nilai yang tampil di Dasbor.

> **Perhatian:** Pada Python requests gunakan `json=data`, bukan `data=data`. Yang terakhir mengirim form dan akan mengembalikan `ERROR_TASK_ABSENT` atau `ERROR_REQUIRED_FIELDS`.

## Respons

Berhasil:

```json
{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```

Gagal:

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

| Field | Keterangan |
| --- | --- |
| `errorId` | 0 berhasil, 1 gagal |
| `errorCode` | Kode error saat gagal; arti dan cara penanganannya ada di [Kode error](https://docs.yescaptcha.com/id/api/errors.md) |
| `errorDescription` | Keterangan teks tentang penyebab kegagalan |
| `taskId` | ID tugas |
| `status` | `processing` (sedang diproses) atau `ready` (selesai) |
| `solution` | Hasil pengenalan; field-nya berbeda menurut jenis tugas, lihat halaman masing-masing jenis tugas |

Gunakan `errorId` dan `errorCode` untuk menentukan hasil, jangan mengurai teks `errorDescription` karena bisa berubah.

## Sinkron dan asinkron

|  | Asinkron | Sinkron |
| --- | --- | --- |
| Jenis apa saja | Jenis yang mengembalikan token (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), halaman verifikasi Cloudflare, `ImageToTextTask`, `ImageToTextTaskM1` | Pengenalan gambar (nama berakhiran `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` mengembalikan | `taskId` | `status: "ready"` dan `solution` |
| Cara mendapat hasil | Panggil `getTaskResult` setiap 5 detik | Tidak perlu memeriksa lagi |

Kolom “Cara pengembalian” di [Jenis tugas dan harga](https://docs.yescaptcha.com/id/tasks.md) menunjukkan mana yang berlaku untuk setiap jenis.

## Polling

1.  Setelah `createTask` mengembalikan `taskId`, tunggu 5 detik lalu panggil `getTaskResult`.
2.  Jika mengembalikan `status: "processing"`, tunggu 5 detik lagi lalu coba kembali; jika `status: "ready"`, hasilnya ada di `solution`.
3.  Jika mengembalikan `errorId: 1`, hentikan polling untuk tugas ini dan tangani sesuai `errorCode`.

-   Permintaan berulang untuk `taskId` yang sama dalam 5 detik langsung mengembalikan `processing`; memeriksa lebih sering tidak membuat hasil lebih cepat didapat.
-   Sebuah tugas umumnya diproses paling lama 110 detik (beberapa jenis 180 sampai 220 detik); jika melewati batas, mengembalikan `ERROR_TASK_TIMEOUT` dan poin dikembalikan otomatis.
-   Hasil disimpan di server sekitar 10 menit; setelah itu `taskId` tidak berlaku dan pemeriksaan mengembalikan `ERROR_TASKID_INVALID`.
-   Memeriksa hasil tidak memotong poin; pemotongan poin hanya terjadi saat membuat tugas.

## Bahasa teks pesan

Untuk pesan jeda otomatis, cache parameter tidak valid, dan penghentian polling, `errorDescription` memilih bahasa berdasarkan header `Accept-Language`: jika diawali `zh` dikembalikan bahasa Mandarin, bahasa lain dikembalikan bahasa Inggris, dan jika header ini tidak ada, keduanya dikembalikan. Keterangan untuk kode error lain tidak terpengaruh.

## Langkah berikutnya

-   [createTask: membuat tugas](https://docs.yescaptcha.com/id/api/create-task.md)
-   [getTaskResult: mengambil hasil](https://docs.yescaptcha.com/id/api/get-task-result.md)
-   [Batas tugas bersamaan dan jeda otomatis](https://docs.yescaptcha.com/id/api/rate-limits.md): terlalu banyak error akan menyebabkan jeda beberapa menit