# หลาย ClientKey: ขีดจำกัด, IP allowlist และเวลาหมดอายุ

> บัญชี YesCaptcha หนึ่งบัญชีมี ClientKey ได้สูงสุด 20 รายการ โดยหักจากยอดคงเหลือของบัญชีเดียวกัน แต่ละรายการตั้งขีดจำกัดการใช้จ่าย (ต่อวัน ต่อสัปดาห์ ต่อเดือน หรือยอดรวมครั้งเดียว รีเซ็ตตามเวลาปักกิ่ง) IP allowlist และเวลาหมดอายุแยกกันได้ และมีผลภายในไม่กี่วินาที

Source: https://docs.yescaptcha.com/th/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/

บัญชี YesCaptcha หนึ่งบัญชีมี `clientKey` ได้สูงสุด 20 รายการ (รวมรายการเดิม) จัดการได้ที่หน้า「คีย์และความปลอดภัย」ในแดชบอร์ด [yescaptcha.com](https://yescaptcha.com/security) ทุก `clientKey` สร้างงานและตรวจสอบยอดคงเหลือได้ และหักจากยอดคงเหลือของบัญชีเดียวกัน แต่ละรายการตั้งขีดจำกัดการใช้จ่าย IP allowlist และเวลาหมดอายุแยกกันได้ และมีผลภายในไม่กี่วินาที

เหมาะกับกรณีเหล่านี้: แยกใช้ระหว่างสภาพแวดล้อมทดสอบกับ production หรือแยกตามโปรเจกต์; แจกให้ลูกค้าปลายทางหรือพันธมิตรโดยกำหนดขีดจำกัดของแต่ละราย; หาก `clientKey` ใดรั่วไหล ก็ลบเฉพาะรายการนั้น โปรแกรมอื่นไม่ได้รับผลกระทบ

## Key หลักและ Key ย่อย

|  | Key หลัก | Key ย่อย |
| --- | --- | --- |
| คืออะไร | `clientKey` เดิม มีบัญชีละหนึ่งรายการ | สร้างเพิ่มนอกเหนือจาก Key หลัก ได้สูงสุด 19 รายการ |
| ขีดจำกัด, IP allowlist, เวลาหมดอายุ | ตั้งได้ | ตั้งได้ |
| รีเซ็ต | ได้: รายการเก่าใช้ไม่ได้ทันที และยอดคงเหลือย้ายไปที่รายการใหม่ | รีเซ็ตไม่ได้ ให้ลบแล้วสร้างใหม่ |
| ลบ | ไม่ได้ | ได้: ใช้ไม่ได้ภายในไม่กี่วินาที และกู้คืนไม่ได้ |

-   รูปแบบเหมือนกันทั้งหมด: 40 ตัวอักษรแรกเป็นคีย์ลับ ตามด้วย ID ผู้ใช้ของคุณ
-   การรีเซ็ต Key หลักไม่กระทบ Key ย่อย
-   ไม่ว่าจะใช้ `clientKey` ใดสร้างงานหรือตรวจสอบยอดคงเหลือ ก็ใช้อินเทอร์เฟซและได้ผลลัพธ์เหมือนกัน ต่างกันเพียงมีการตรวจสอบขีดจำกัด IP allowlist และเวลาหมดอายุเพิ่ม

## สร้าง ClientKey ใหม่

1.  เข้าสู่ระบบที่ [yescaptcha.com](https://yescaptcha.com/) แล้วเปิดหน้า「คีย์และความปลอดภัย」([yescaptcha.com/security](https://yescaptcha.com/security))
2.  ใน “Key ทั้งหมด” คลิก “สร้าง Key ย่อย” ชื่อ (ไม่เกิน 40 ตัวอักษร) ขีดจำกัด IP allowlist และเวลาหมดอายุไม่ต้องกรอกก็ได้ และแก้ไขภายหลังได้
3.  ยืนยันตัวตนอีกครั้งตามที่ระบบแจ้ง การสร้าง แก้ไข และลบต้องยืนยันตัวตนทุกครั้ง
4.  หลังสร้างแล้วให้คัดลอก `clientKey` แบบเต็มไปตั้งค่าในโปรแกรม ภายหลังสามารถคลิกไอคอนรูปตาในรายการเพื่อดูอีกครั้งได้

> **หมายเหตุ:** การสร้าง แก้ไข และลบมีผลภายในไม่กี่วินาที หากเรียกใช้ทันทีหลังสร้าง อาจได้รับ `ERROR_KEY_DOES_NOT_EXIST` ให้รอสักครู่แล้วลองใหม่ ภายในไม่กี่วินาทีหลังลบหรือเข้มงวดการตั้งค่าขึ้น คำขอที่กำลังส่งอยู่อาจยังถูกประมวลผลตามการตั้งค่าเดิม

## ขีดจำกัดการใช้จ่าย

ขีดจำกัดกำหนดว่า `clientKey` หนึ่งใช้จ่ายได้สูงสุดกี่พอยต์ในหนึ่งรอบ (1,000 พอยต์ = ¥1) ตั้งได้ตั้งแต่ 1 ถึง 10,000,000,000 พอยต์ มีสี่รอบ รีเซ็ตตามเวลาปักกิ่ง (UTC+8):

| รอบ | รีเซ็ตเมื่อใด |
| --- | --- |
| ต่อวัน | ทุกวันเวลา 00:00 |
| ต่อสัปดาห์ | ทุกวันจันทร์เวลา 00:00 |
| ต่อเดือน | วันที่ 1 ของทุกเดือนเวลา 00:00 |
| ยอดรวมครั้งเดียว | ไม่รีเซ็ต เมื่อใช้หมดแล้ว `clientKey` นี้จะสร้างงานไม่ได้อีก หากต้องการใช้ต่อให้เพิ่มขีดจำกัด |

-   คำนวณตามพอยต์ที่หักจริง: พอยต์ที่คืนจากการจดจำล้มเหลวหรือหมดเวลา จะคืนเข้าขีดจำกัดด้วย
-   เมื่อขีดจำกัดที่เหลือในรอบนี้ไม่พอสำหรับการหักพอยต์ของงานนี้ `createTask` จะคืนค่า [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) ไม่หักพอยต์ และไม่นับรวมใน[การหยุดชั่วคราวอัตโนมัติ](https://docs.yescaptcha.com/th/api/rate-limits.md)
-   รายการในแดชบอร์ดแสดงว่าแต่ละ `clientKey` ใช้ไปเท่าไรในรอบนี้ และจะรีเซ็ตครั้งถัดไปเมื่อใด
-   ขีดจำกัดไม่ใช่ยอดคงเหลือแยกต่างหาก: ทุก `clientKey` หักจากยอดคงเหลือของบัญชีเดียวกัน เมื่อยอดคงเหลือของบัญชีไม่พอจะคืนค่า `ERROR_ZERO_BALANCE` ตามปกติ

เมื่อเรียก [`getBalance`](https://docs.yescaptcha.com/th/api/get-balance.md) ด้วย `clientKey` ที่ตั้งขีดจำกัดไว้ `balance` จะเป็นค่าที่น้อยกว่าระหว่างยอดคงเหลือของบัญชีกับขีดจำกัดที่เหลือในรอบนี้ และมีฟิลด์ `keyQuotaRemaining` เพิ่มเข้ามา (ขีดจำกัดที่เหลือ หน่วยพอยต์) `clientKey` ที่ไม่ได้ตั้งขีดจำกัดจะไม่มีฟิลด์นี้ และผลลัพธ์เหมือนเดิม

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

## IP allowlist

`clientKey` ที่ตั้ง IP allowlist ไว้ จะใช้ได้เฉพาะคำขอที่ส่งจาก IP ในรายการเท่านั้น หากเว้นว่างไว้คือไม่จำกัด

-   ให้กรอก **IP สาธารณะของเครื่องที่เรียกใช้ API ของ YesCaptcha** (IP ขาออก) ไม่ใช่พร็อกซีในพารามิเตอร์ของงาน หากเรียกจากหลายเครื่อง ต้องเพิ่ม IP สาธารณะของทุกเครื่อง
-   หนึ่งบรรทัดต่อหนึ่งที่อยู่ IPv4 หรือ IPv6 หรือช่วง CIDR ได้สูงสุด 50 รายการ ที่อยู่เดี่ยวหมายถึงอนุญาตเฉพาะ IP นั้น
-   ช่วง IP ต้องเขียนเป็นที่อยู่เครือข่าย: `203.0.113.0/24` ใช้ได้ แต่ `203.0.113.5/24` ใช้ไม่ได้ (บิตโฮสต์ไม่เป็น 0)

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

-   เมื่อ IP ของคำขอไม่อยู่ในรายการ `createTask` และ `getBalance` จะคืนค่า [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) ไม่หักพอยต์ และไม่นับรวมในการหยุดชั่วคราวอัตโนมัติ
-   หาก IP ขาออกเปลี่ยนได้ (อินเทอร์เน็ตบ้าน, cloud function, egress ที่หมุนเวียน) อย่าตั้งค่า หรือตั้งเป็นทั้งช่วง

## เวลาหมดอายุ

-   `clientKey` ใดก็ได้ (รวม Key หลัก) ตั้งเวลาหมดอายุได้ ต้องอยู่ภายในสิบปี และแก้ไขหรือลบออกได้ทุกเมื่อ
-   หลังหมดอายุ การเรียก `createTask` และ `getBalance` ด้วยรายการนั้นจะคืนค่า [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_EXPIRED) และไม่หักพอยต์ งานที่สร้างไว้แล้วยังใช้ `getTaskResult` ดึงผลได้ตามปกติ
-   `clientKey` ที่ไม่ได้ใช้งานเป็นเวลานาน ระบบจะตั้งเวลาหมดอายุให้เพื่อความปลอดภัยของบัญชี และส่งอีเมลแจ้งเตือนก่อนหมดอายุ เวลาหมดอายุแบบนี้แก้ไขไม่ได้: ให้สร้าง Key หลักใหม่ (ยอดคงเหลือย้ายไปที่รายการใหม่โดยอัตโนมัติ) หรือสร้าง `clientKey` ใหม่ แล้วอัปเดตในโปรแกรม

## ยอดคงเหลือ ขีดจำกัดงานพร้อมกัน และการหยุดชั่วคราวอัตโนมัติ

-   **ยอดคงเหลือ**: ทุก `clientKey` หักจากยอดคงเหลือของบัญชีเดียวกัน การเติมเงิน โบนัส VIP รางวัลแนะนำเพื่อน และส่วนแบ่งรายได้นักพัฒนา ล้วนคิดตามบัญชี ไม่เกี่ยวกับว่าใช้ `clientKey` ใด
-   **ขีดจำกัดงานพร้อมกัน**: คิดตามบัญชี ทุก `clientKey` ใช้เพดานเดียวกันรวมกัน ดู[ขีดจำกัดงานพร้อมกันและการหยุดชั่วคราวอัตโนมัติ](https://docs.yescaptcha.com/th/api/rate-limits.md)
-   **การหยุดชั่วคราวอัตโนมัติ**: คิดแยกตาม `clientKey` หาก `clientKey` หนึ่งมีข้อผิดพลาดมากเกินไปจนถูกหยุดชั่วคราว รายการอื่นไม่ได้รับผลกระทบ

## รหัสข้อผิดพลาดที่เกี่ยวข้อง

| รหัสข้อผิดพลาด | คืนค่าเมื่อใด |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | ขีดจำกัดที่เหลือในรอบนี้ไม่พอสำหรับงานนี้ (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | IP ของคำขอไม่อยู่ใน IP allowlist ของ `clientKey` นี้ (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/th/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey` หมดอายุแล้ว (`createTask`, `getBalance`) |

ทั้งสามรายการไม่หักพอยต์ วิธีจัดการดู[รหัสข้อผิดพลาด](https://docs.yescaptcha.com/th/api/errors.md)