# 여러 clientKey: 한도, IP 허용 목록, 만료 시각

> YesCaptcha 계정 하나에 clientKey를 최대 20개 만들 수 있고, 모두 같은 계정 잔액에서 포인트가 차감돼요. 각 clientKey마다 사용 한도(매일, 매주, 매월 또는 1회성, 베이징 시간 기준으로 초기화), IP 허용 목록, 만료 시각을 따로 설정할 수 있고, 몇 초 안에 적용돼요.

Source: https://docs.yescaptcha.com/ko/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`로 작업을 만들고 잔액을 조회할 수 있고, 포인트는 모두 같은 계정 잔액에서 차감돼요. 각 `clientKey`마다 한도, IP 허용 목록, 만료 시각을 따로 설정할 수 있고, 몇 초 안에 적용돼요.

이런 경우에 쓰면 좋아요. 테스트 환경과 운영 환경, 또는 프로젝트별로 키를 나눠 쓸 때. 하위 고객이나 파트너에게 키를 나눠 주고 각자 한도를 둘 때. 어떤 `clientKey`가 유출돼도 그 키만 삭제하면 다른 프로그램은 영향을 받지 않아요.

## 기본 Key와 하위 Key

|  | 기본 Key | 하위 Key |
| --- | --- | --- |
| 어떤 키인가요 | 원래 쓰던 `clientKey`예요. 계정마다 하나예요 | 기본 Key 외에 새로 만든 키예요. 최대 19개예요 |
| 한도, IP 허용 목록, 만료 시각 | 설정할 수 있어요 | 설정할 수 있어요 |
| 재설정 | 가능해요. 기존 키는 즉시 사용할 수 없게 되고 잔액이 새 키로 옮겨져요 | 재설정할 수 없어요. 삭제하고 새로 만드세요 |
| 삭제 | 할 수 없어요 | 할 수 있어요. 몇 초 안에 사용할 수 없게 되고 복구할 수 없어요 |

-   형식은 모두 같아요. 앞 40자는 비밀 키이고, 뒤는 내 사용자 ID예요.
-   기본 Key를 재설정해도 하위 Key에는 영향이 없어요.
-   어떤 `clientKey`로 작업을 만들고 잔액을 조회하든 API와 응답은 같아요. 한도, 허용 목록, 만료 시각을 추가로 확인할 뿐이에요.

## clientKey 만들기

1.  [yescaptcha.com](https://yescaptcha.com/)에 로그인하고 “키와 보안” 페이지([yescaptcha.com/security](https://yescaptcha.com/security))를 여세요.
2.  “전체 Key”에서 “하위 Key 만들기”를 클릭하세요. 이름(최대 40자), 한도, IP 허용 목록, 만료 시각은 모두 비워 둘 수 있고, 나중에 바꿀 수도 있어요.
3.  안내에 따라 본인 확인을 한 번 더 하세요. 만들기, 수정, 삭제 모두 본인 확인이 필요해요.
4.  만든 뒤 전체 `clientKey`를 복사해서 프로그램에 설정하세요. 나중에 목록에서 눈 아이콘을 클릭해 다시 볼 수도 있어요.

> **참고:** 만들기, 수정, 삭제는 모두 몇 초 안에 적용돼요. 만들자마자 호출하면 `ERROR_KEY_DOES_NOT_EXIST`가 반환될 수 있으니 몇 초 뒤에 다시 시도하세요. 삭제하거나 설정을 더 엄격하게 바꾼 직후 몇 초 동안은 이미 전송 중인 요청이 이전 설정대로 처리될 수 있어요.

## 사용 한도

한도는 `clientKey` 하나가 한 주기 동안 최대 몇 포인트까지 쓸 수 있는지를 제한해요(1,000포인트 = ¥1). 1에서 10,000,000,000포인트까지 설정할 수 있어요. 주기는 네 가지이고, 베이징 시간(UTC+8) 기준으로 초기화돼요.

| 주기 | 초기화 시점 |
| --- | --- |
| 매일 | 매일 0시 |
| 매주 | 매주 월요일 0시 |
| 매월 | 매월 1일 0시 |
| 1회성 총액 | 초기화되지 않아요. 다 쓰면 이 `clientKey`로는 더 이상 작업을 만들 수 없어요. 계속 쓰려면 한도를 올리세요 |

-   실제로 차감된 포인트를 기준으로 계산해요. 인식 실패나 시간 초과로 환불된 포인트는 한도에도 되돌아가요.
-   이번 주기에 남은 한도가 작업의 포인트 차감액보다 적으면 `createTask`가 [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED)를 반환해요. 포인트는 차감되지 않고, [자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)에도 포함되지 않아요.
-   대시보드 목록에서 각 `clientKey`가 이번 주기에 얼마나 썼는지, 다음 초기화가 언제인지 볼 수 있어요.
-   한도는 별도의 잔액이 아니에요. 모든 `clientKey`가 같은 계정 잔액에서 차감되고, 계정 잔액이 부족하면 평소처럼 `ERROR_ZERO_BALANCE`가 반환돼요.

한도를 설정한 `clientKey`로 [`getBalance`](https://docs.yescaptcha.com/ko/api/get-balance.md)를 호출하면 `balance`는 계정 잔액과 이번 주기의 남은 한도 중 더 작은 값이에요. 또한 `keyQuotaRemaining`(남은 한도, 포인트) 필드가 추가돼요. 한도를 설정하지 않은 `clientKey`에는 이 필드가 없고, 응답은 이전과 같아요.

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

## IP 허용 목록

IP 허용 목록을 설정한 `clientKey`는 목록에 있는 IP에서 보낸 요청만 사용할 수 있어요. 비워 두면 제한이 없어요.

-   **YesCaptcha API를 호출하는 머신의 공인 IP**(외부로 나가는 IP)를 입력하세요. 작업 파라미터에 넣는 프록시가 아니에요. 여러 머신에서 호출한다면 각 머신의 공인 IP를 모두 추가해야 해요.
-   한 줄에 IPv4 또는 IPv6 주소나 CIDR 대역을 하나씩, 최대 50개까지 입력할 수 있어요. 주소 하나만 쓰면 그 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/ko/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED)를 반환해요. 포인트는 차감되지 않고, 자동 일시 중지에도 포함되지 않아요.
-   외부로 나가는 IP가 바뀌는 환경(가정용 인터넷, 클라우드 함수, 순환하는 출구 IP)에서는 설정하지 않거나, 대역 전체를 허용하세요.

## 만료 시각

-   기본 Key를 포함해 어떤 `clientKey`든 10년 이내로 만료 시각을 설정할 수 있어요. 이후 언제든 수정하거나 없앨 수 있어요.
-   만료된 뒤에는 그 키로 `createTask`, `getBalance`를 호출하면 [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED)가 반환되고 포인트는 차감되지 않아요. 이미 만든 작업은 `getTaskResult`로 계속 결과를 가져올 수 있어요.
-   오랫동안 사용하지 않은 `clientKey`에는 계정 보안을 위해 시스템이 만료 시각을 설정하고, 만료 전에 이메일로 알려 드려요. 이 만료 시각은 수정할 수 없어요. 기본 Key를 다시 생성하거나(잔액이 새 키로 자동으로 옮겨져요) 새 `clientKey`를 만든 뒤 프로그램에 반영하세요.

## 잔액, 동시 작업 수 제한, 자동 일시 중지

-   **잔액**: 모든 `clientKey`가 같은 계정 잔액에서 차감돼요. 충전, VIP 보너스, 추천 보상, 개발자 수익 배분은 모두 계정 기준이고, 어떤 `clientKey`를 쓰는지와 관계없어요.
-   **동시 작업 수 제한**: 계정 기준으로 계산해요. 모든 `clientKey`가 같은 상한을 함께 적용받아요. [동시 작업 수 제한과 자동 일시 중지](https://docs.yescaptcha.com/ko/api/rate-limits.md)를 참고하세요.
-   **자동 일시 중지**: `clientKey`별로 따로 계산해요. 한 `clientKey`가 오류가 너무 많아 일시 중지돼도 다른 키에는 영향이 없어요.

## 관련 오류 코드

| 오류 코드 | 반환되는 경우 |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | 이번 주기에 남은 한도가 이 작업에 부족해요(`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | 요청한 IP가 이 `clientKey`의 IP 허용 목록에 없어요(`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/ko/api/errors.md#ERROR_KEY_EXPIRED) | `clientKey`가 만료됐어요(`createTask`, `getBalance`) |

세 가지 모두 포인트가 차감되지 않아요. 해결 방법은 [오류 코드](https://docs.yescaptcha.com/ko/api/errors.md)를 참고하세요.