# Várias clientKeys: limite de gastos, IPs permitidos e expiração

> Uma conta YesCaptcha pode ter até 20 clientKeys, todas usando o mesmo saldo da conta. Cada uma pode ter seu próprio limite de gastos (por dia, semana ou mês, ou um total único, zerado no horário de Pequim), IPs permitidos e data de expiração, com efeito em poucos segundos.

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

Uma conta YesCaptcha pode ter até 20 `clientKey`s (incluindo a original), gerenciadas na página Chaves e segurança do Painel em [yescaptcha.com](https://yescaptcha.com/security). Toda `clientKey` pode criar tarefas e consultar o saldo, e todas usam o mesmo saldo da conta. Cada uma pode ter seu próprio limite de gastos, IPs permitidos e data de expiração, e as alterações entram em vigor em poucos segundos.

Usos típicos: separar ambiente de teste e de produção, ou projetos diferentes; repassar chaves a clientes ou parceiros seus, cada um com seu limite; e, se uma `clientKey` vazar, excluir apenas essa, sem afetar os outros programas.

## Chave principal e subchaves

|  | Chave principal | Subchave |
| --- | --- | --- |
| O que é | A `clientKey` original, uma por conta | Qualquer chave criada além da principal; até 19 |
| Limite, IPs permitidos, expiração | Pode definir | Pode definir |
| Redefinir | Sim: a antiga deixa de funcionar na hora e o saldo passa para a nova | Não; exclua e crie outra |
| Excluir | Não | Sim: deixa de funcionar em poucos segundos e não pode ser restaurada |

-   Todas têm o mesmo formato: os primeiros 40 caracteres são a chave secreta, seguidos do seu ID de usuário.
-   Redefinir a chave principal não afeta as subchaves.
-   Seja qual for a `clientKey` usada para criar tarefas ou consultar o saldo, a API e as respostas são as mesmas; a única diferença são as verificações adicionais de limite, IPs permitidos e expiração.

## Criar uma clientKey

1.  Faça login em [yescaptcha.com](https://yescaptcha.com/) e abra a página Chaves e segurança ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  Em “Todas as chaves”, clique em “Nova subchave”. Nome (até 40 caracteres), limite, IPs permitidos e expiração são opcionais e podem ser alterados depois.
3.  Verifique sua identidade novamente quando solicitado. Criar, alterar e excluir exigem essa verificação.
4.  Depois de criada, copie a `clientKey` completa e configure-a no seu programa. Você também pode vê-la novamente depois, clicando no ícone de olho na lista.

> **Nota:** Criar, alterar e excluir entram em vigor em poucos segundos. Uma chamada feita logo após criar a chave pode retornar `ERROR_KEY_DOES_NOT_EXIST`; aguarde alguns segundos e tente de novo. Nos segundos seguintes à exclusão de uma chave ou ao endurecimento de suas configurações, requisições já em andamento ainda podem ser processadas com as configurações antigas.

## Limite de gastos

O limite define quantos pontos uma `clientKey` pode gastar em um período (1,000 pontos = ¥1), de 1 a 10,000,000,000 pontos. Há quatro períodos, zerados no horário de Pequim (UTC+8):

| Período | Quando zera |
| --- | --- |
| Por dia | Todo dia às 00:00 |
| Por semana | Toda segunda-feira às 00:00 |
| Por mês | Todo dia 1 às 00:00 |
| Total único | Nunca zera. Depois de esgotado, esta `clientKey` não pode mais criar tarefas; aumente o limite para continuar usando |

-   Conta os pontos efetivamente cobrados: os pontos devolvidos por falha de reconhecimento ou timeout também voltam ao limite.
-   Se o que resta do limite no período atual não cobre a cobrança de pontos da tarefa, `createTask` retorna [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED), sem cobrar pontos e sem contar para a [pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
-   A lista no Painel mostra quanto cada `clientKey` já usou no período atual e quando será zerada novamente.
-   O limite não é um saldo separado: todas as `clientKey`s usam o mesmo saldo da conta, e quando o saldo da conta acaba você recebe `ERROR_ZERO_BALANCE`, como de costume.

Ao chamar [`getBalance`](https://docs.yescaptcha.com/pt/api/get-balance.md) com uma `clientKey` que tem limite, `balance` é o menor valor entre o saldo da conta e o que resta do limite no período atual, e há um campo extra `keyQuotaRemaining` (limite restante, em pontos). Uma `clientKey` sem limite não recebe esse campo, e a resposta é igual à de antes.

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

## IPs permitidos

Uma `clientKey` com IPs permitidos só funciona para requisições enviadas dos IPs da lista. Deixe em branco para não restringir.

-   Informe o **IP público da máquina que chama a API do YesCaptcha** (o IP de saída), não o proxy dos parâmetros da tarefa. Se várias máquinas fazem chamadas, adicione o IP público de cada uma.
-   Um endereço IPv4 ou IPv6, ou faixa CIDR, por linha, até 50 entradas. Um endereço isolado permite somente esse IP.
-   Escreva as faixas com o endereço de rede: `203.0.113.0/24` é aceito, `203.0.113.5/24` não (os bits de host não são zero).

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

-   Se o IP da requisição não estiver na lista, `createTask` e `getBalance` retornam [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED), sem cobrar pontos e sem contar para a pausa automática.
-   Se o seu IP de saída muda (banda larga residencial, funções em nuvem, saída rotativa), não defina a lista ou permita a faixa inteira.

## Expiração

-   Qualquer `clientKey`, inclusive a chave principal, pode ter uma data de expiração dentro de dez anos; depois você pode alterá-la ou removê-la a qualquer momento.
-   Depois de expirada, `createTask` e `getBalance` com essa chave retornam [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED), sem cobrar pontos. Tarefas já criadas ainda podem ter o resultado obtido com `getTaskResult`.
-   Se uma `clientKey` fica muito tempo sem uso, o sistema define uma data de expiração para proteger a conta e envia um e-mail antes do vencimento. Essa expiração não pode ser alterada: gere uma nova chave principal (o saldo passa para ela automaticamente) ou crie outra `clientKey`, e atualize o seu programa.

## Saldo, limite de tarefas simultâneas e pausa automática

-   **Saldo**: todas as `clientKey`s usam o mesmo saldo da conta. Recarga, bônus de VIP, recompensa por indicação e participação do desenvolvedor pertencem à conta, seja qual for a `clientKey` usada.
-   **Limite de tarefas simultâneas**: contado por conta; todas as `clientKey`s juntas compartilham o mesmo limite. Veja [Limite de tarefas simultâneas e pausa automática](https://docs.yescaptcha.com/pt/api/rate-limits.md).
-   **Pausa automática**: contada por `clientKey`. Se uma `clientKey` for pausada por erros demais, as outras não são afetadas.

## Códigos de erro relacionados

| Código de erro | Quando é retornado |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | O que resta do limite no período atual não cobre esta tarefa (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | O IP da requisição não está nos IPs permitidos desta `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/pt/api/errors.md#ERROR_KEY_EXPIRED) | A `clientKey` expirou (`createTask`, `getBalance`) |

Nenhum destes cobra pontos. Veja [Códigos de erro](https://docs.yescaptcha.com/pt/api/errors.md) para saber o que fazer.