# Beberapa clientKey: batas penggunaan, daftar IP yang diizinkan, dan masa berlaku

> Satu akun YesCaptcha dapat memiliki hingga 20 clientKey yang memotong saldo akun yang sama. Setiap key dapat diberi batas penggunaan sendiri (per hari, per minggu, per bulan, atau total sekali pakai, direset menurut waktu Beijing), daftar IP yang diizinkan, dan masa berlaku, dan berlaku dalam hitungan detik.

Source: https://docs.yescaptcha.com/id/account/client-keys/ · Last verified: 2026-10-29

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

Satu akun YesCaptcha dapat memiliki hingga 20 `clientKey` (termasuk yang asli), yang dikelola di halaman Kunci & keamanan pada dasbor [yescaptcha.com](https://yescaptcha.com/security). Setiap `clientKey` dapat membuat tugas dan memeriksa saldo, dan semuanya memotong saldo akun yang sama. Setiap key dapat diberi batas penggunaan, daftar IP yang diizinkan, dan masa berlaku sendiri, dan perubahan berlaku dalam hitungan detik.

Cocok untuk kasus berikut: memisahkan lingkungan pengujian dan produksi atau proyek yang berbeda; membagikan key ke pelanggan hilir atau mitra, masing-masing dengan batas sendiri; dan jika satu `clientKey` bocor, Anda cukup menghapus key itu saja tanpa memengaruhi program lain.

## Key utama dan Sub-Key

|  | Key utama | Sub-Key |
| --- | --- | --- |
| Yang mana | `clientKey` asli, satu per akun | Key yang dibuat selain key utama, hingga 19 |
| Batas, daftar IP yang diizinkan, masa berlaku | Dapat diatur | Dapat diatur |
| Reset | Bisa: key lama langsung tidak berlaku dan saldo berpindah ke key baru | Tidak bisa; hapus lalu buat yang baru |
| Hapus | Tidak bisa | Bisa: tidak berlaku dalam hitungan detik dan tidak dapat dipulihkan |

-   Formatnya sama: 40 karakter pertama adalah kunci rahasia, diikuti ID pengguna Anda.
-   Mereset key utama tidak memengaruhi Sub-Key.
-   Apa pun `clientKey` yang Anda gunakan untuk membuat tugas atau memeriksa saldo, API dan responsnya sama; hanya ada tambahan pemeriksaan batas, daftar IP yang diizinkan, dan masa berlaku.

## Membuat clientKey

1.  Masuk ke [yescaptcha.com](https://yescaptcha.com/), lalu buka halaman Kunci & keamanan ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  Di “Semua Key”, klik “Sub-Key baru”. Nama (maksimal 40 karakter), batas, daftar IP yang diizinkan, dan masa berlaku boleh dikosongkan dan dapat diubah nanti.
3.  Verifikasi identitas sekali lagi saat diminta. Membuat, mengubah, dan menghapus key semuanya memerlukan verifikasi ini.
4.  Setelah dibuat, salin `clientKey` lengkap dan atur di program Anda. Nanti Anda juga dapat melihatnya lagi dengan mengklik ikon mata di daftar.

> **Catatan:** Membuat, mengubah, dan menghapus key berlaku dalam hitungan detik. Panggilan yang dilakukan tepat setelah key dibuat mungkin mengembalikan `ERROR_KEY_DOES_NOT_EXIST`; tunggu beberapa detik lalu coba lagi. Selama beberapa detik setelah key dihapus atau pengaturannya diperketat, permintaan yang sedang dikirim mungkin masih diproses dengan pengaturan lama.

## Batas penggunaan

Batas penggunaan membatasi jumlah poin maksimum yang dapat dipakai sebuah `clientKey` dalam satu periode (1,000 poin = ¥1). Batas dapat diatur dari 1 hingga 10,000,000,000 poin. Ada empat periode, direset menurut waktu Beijing (UTC+8):

| Periode | Kapan direset |
| --- | --- |
| Per hari | Setiap hari pukul 00:00 |
| Per minggu | Setiap Senin pukul 00:00 |
| Per bulan | Setiap tanggal 1 pukul 00:00 |
| Total sekali pakai | Tidak pernah direset. Setelah habis, `clientKey` ini tidak dapat membuat tugas lagi; naikkan batas untuk terus menggunakannya |

-   Dihitung berdasarkan poin yang benar-benar dipotong: poin yang dikembalikan karena pengenalan gagal atau timeout juga dikembalikan ke batas.
-   Jika sisa batas pada periode saat ini tidak cukup untuk pemotongan poin tugas, `createTask` mengembalikan [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED). Poin tidak dipotong dan tidak dihitung ke [jeda otomatis](https://docs.yescaptcha.com/id/api/rate-limits.md).
-   Daftar di dasbor menampilkan berapa yang sudah dipakai setiap `clientKey` pada periode ini dan kapan reset berikutnya.
-   Batas bukan saldo terpisah: semua `clientKey` memotong saldo akun yang sama, dan jika saldo akun tidak cukup, `ERROR_ZERO_BALANCE` dikembalikan seperti biasa.

Jika Anda memanggil [`getBalance`](https://docs.yescaptcha.com/id/api/get-balance.md) dengan `clientKey` yang memiliki batas, `balance` adalah nilai yang lebih kecil antara saldo akun dan sisa batas pada periode ini, dan ada tambahan field `keyQuotaRemaining` (sisa batas, dalam poin). `clientKey` tanpa batas tidak memiliki field ini, dan responsnya sama seperti sebelumnya.

```json
{
  "errorId": 0,
  "balance": 20000,
  "softBalance": 0,
  "inviteBalance": 0,
  "inviteBy": 0,
  "keyQuotaRemaining": 20000
}
```

## Daftar IP yang diizinkan

`clientKey` yang memiliki daftar IP yang diizinkan hanya dapat digunakan untuk permintaan yang dikirim dari IP dalam daftar. Kosongkan untuk tanpa batasan.

-   Isi dengan **IP publik mesin yang memanggil API YesCaptcha** (IP keluar), bukan proxy di parameter tugas. Jika memanggil dari beberapa mesin, tambahkan IP publik masing-masing.
-   Satu alamat IPv4 atau IPv6, atau rentang CIDR, per baris, maksimal 50 entri. Satu alamat berarti hanya IP itu yang diizinkan.
-   Tulis rentang sebagai alamat jaringan: `203.0.113.0/24` diterima, `203.0.113.5/24` tidak (bit host bukan 0).

```text
203.0.113.10
198.51.100.0/24
2001:db8::/32
```

-   Jika IP permintaan tidak ada dalam daftar, `createTask` dan `getBalance` mengembalikan [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED). Poin tidak dipotong dan tidak dihitung ke jeda otomatis.
-   Jika IP keluar Anda berubah-ubah (internet rumah, cloud function, IP keluar yang dirotasi), jangan atur daftar ini, atau izinkan seluruh rentang.

## Masa berlaku

-   Setiap `clientKey`, termasuk key utama, dapat diberi masa berlaku dalam sepuluh tahun ke depan. Anda dapat mengubah atau menghapusnya kapan saja.
-   Setelah kedaluwarsa, `createTask` dan `getBalance` dengan key tersebut mengembalikan [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_EXPIRED) dan poin tidak dipotong. Tugas yang sudah dibuat tetap dapat diambil hasilnya dengan `getTaskResult`.
-   Jika sebuah `clientKey` lama tidak digunakan, sistem akan mengatur masa berlaku untuknya demi keamanan akun dan mengirim email pengingat sebelum kedaluwarsa. Masa berlaku ini tidak dapat diubah: buat ulang key utama (saldo berpindah otomatis ke yang baru) atau buat `clientKey` baru, lalu perbarui di program Anda.

## Saldo, batas tugas bersamaan, dan jeda otomatis

-   **Saldo**: semua `clientKey` memotong saldo akun yang sama. Isi saldo, bonus VIP, hadiah referral, dan bagi hasil developer semuanya dihitung per akun, apa pun `clientKey` yang digunakan.
-   **Batas tugas bersamaan**: dihitung per akun; semua `clientKey` berbagi batas yang sama. Lihat [Batas tugas bersamaan dan jeda otomatis](https://docs.yescaptcha.com/id/api/rate-limits.md).
-   **Jeda otomatis**: dihitung per `clientKey`. Jika satu `clientKey` dijeda karena terlalu banyak error, key lain tidak terpengaruh.

## Kode error terkait

| Kode error | Kapan dikembalikan |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Sisa batas pada periode ini tidak cukup untuk tugas ini (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | IP permintaan tidak ada dalam daftar IP yang diizinkan untuk `clientKey` ini (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/id/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` sudah kedaluwarsa (`createTask`, `getBalance`) |

Ketiganya tidak memotong poin. Cara menanganinya ada di [Kode error](https://docs.yescaptcha.com/id/api/errors.md).