# Varios ClientKey: límites de gasto, lista blanca de IP y vencimiento

> Una cuenta de YesCaptcha puede tener hasta 20 ClientKey, todas con cargo al mismo saldo de la cuenta. Cada una puede tener su propio límite de gasto (diario, semanal, mensual o total único, con reinicio en hora de Beijing), lista blanca de IP y vencimiento, con efecto en pocos segundos.

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

Una cuenta de YesCaptcha puede tener hasta 20 `clientKey` (incluida la original), que se administran en la página «Claves y seguridad» del panel de [yescaptcha.com](https://yescaptcha.com/security). Cada `clientKey` puede crear tareas y consultar el saldo, y todas descuentan del mismo saldo de la cuenta. Cada una puede tener su propio límite de gasto, lista blanca de IP y vencimiento, y los cambios surten efecto en pocos segundos.

Casos de uso habituales: separar los entornos de prueba y producción o los distintos proyectos; entregar claves a tus clientes o socios, cada uno con su propio límite; y, si una `clientKey` se filtra, eliminar solo esa sin afectar a los demás programas.

## Key principal y SubKey

|  | Key principal | SubKey |
| --- | --- | --- |
| Qué es | La `clientKey` original; una por cuenta | Las que se crean además de la Key principal; hasta 19 |
| Límite, lista blanca de IP, vencimiento | Se pueden configurar | Se pueden configurar |
| Restablecer | Sí: la anterior deja de funcionar de inmediato y el saldo pasa a la nueva | No se puede; elimínala y crea otra |
| Eliminar | No | Sí: deja de funcionar en pocos segundos y no se puede recuperar |

-   Todas tienen el mismo formato: los primeros 40 caracteres son la clave y después va tu ID de usuario.
-   Restablecer la Key principal no afecta a las SubKey.
-   Uses la `clientKey` que uses para crear tareas o consultar el saldo, la API y las respuestas son iguales; la única diferencia son las comprobaciones adicionales de límite, lista blanca de IP y vencimiento.

## Crear una clientKey

1.  Inicia sesión en [yescaptcha.com](https://yescaptcha.com/) y abre la página «Claves y seguridad» ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  En «Todas las Keys», haz clic en «Nueva subKey». El nombre (hasta 40 caracteres), el límite, la lista blanca de IP y el vencimiento son opcionales y se pueden cambiar después.
3.  Confirma tu identidad de nuevo cuando se te pida. Crear, modificar y eliminar requieren esta confirmación.
4.  Tras crearla, copia la `clientKey` completa y configúrala en tu programa. También puedes volver a verla después con el icono del ojo en la lista.

> **Nota:** Crear, modificar y eliminar surten efecto en pocos segundos. Si llamas justo después de crear una clave, puede devolver `ERROR_KEY_DOES_NOT_EXIST`; espera unos segundos y vuelve a intentarlo. Durante unos segundos después de eliminar una clave o de endurecer su configuración, las solicitudes que ya están en curso pueden procesarse con la configuración anterior.

## Límite de gasto

El límite fija cuántos puntos puede gastar una `clientKey` en un periodo (1,000 puntos = ¥1), entre 1 y 10,000,000,000 puntos. Hay cuatro periodos, con reinicio en hora de Beijing (UTC+8):

| Periodo | Cuándo se reinicia |
| --- | --- |
| Diario | Todos los días a las 00:00 |
| Semanal | Todos los lunes a las 00:00 |
| Mensual | El día 1 de cada mes a las 00:00 |
| Total único | No se reinicia. Cuando se agota, esta `clientKey` ya no puede crear tareas; sube el límite para seguir usándola |

-   Se cuentan los puntos realmente cobrados: los puntos reembolsados por tareas fallidas o con tiempo agotado también vuelven al límite.
-   Si el límite que queda en el periodo actual no alcanza para el cobro de puntos de la tarea, `createTask` devuelve [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED). No se cobran puntos y no cuenta para la [pausa automática](https://docs.yescaptcha.com/es/api/rate-limits.md).
-   La lista del panel muestra cuánto ha usado cada `clientKey` en el periodo actual y cuándo se reinicia.
-   El límite no es un saldo aparte: todas las `clientKey` descuentan del mismo saldo de la cuenta, y cuando el saldo de la cuenta no alcanza se devuelve `ERROR_ZERO_BALANCE` como siempre.

Si llamas a [`getBalance`](https://docs.yescaptcha.com/es/api/get-balance.md) con una `clientKey` que tiene límite, `balance` es el menor entre el saldo de la cuenta y el límite restante del periodo actual, y se añade el campo `keyQuotaRemaining` (límite restante, en puntos). Una `clientKey` sin límite no incluye este campo y la respuesta es igual que antes.

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

## Lista blanca de IP

Una `clientKey` con lista blanca de IP solo funciona para solicitudes enviadas desde las IP de la lista. Déjala vacía para no restringir.

-   Escribe la **IP pública de la máquina que llama a la API de YesCaptcha** (su IP de salida), no el proxy de los parámetros de la tarea. Si llamas desde varias máquinas, añade la IP pública de cada una.
-   Una dirección IPv4 o IPv6, o un rango CIDR, por línea, hasta 50 entradas. Una dirección sola permite únicamente esa IP.
-   Escribe los rangos como dirección de red: `203.0.113.0/24` es válido, `203.0.113.5/24` no (los bits de host no son 0).

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

-   Si la IP de la solicitud no está en la lista, `createTask` y `getBalance` devuelven [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED). No se cobran puntos y no cuenta para la pausa automática.
-   Si tu IP de salida cambia (banda ancha doméstica, funciones en la nube, salidas rotativas), no configures la lista, o permite el rango completo.

## Vencimiento

-   Cualquier `clientKey`, incluida la Key principal, puede tener una fecha de vencimiento dentro de los próximos diez años; después puedes modificarla o quitarla en cualquier momento.
-   Una vez vencida, `createTask` y `getBalance` con esa clave devuelven [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_EXPIRED) y no se cobran puntos. Las tareas ya creadas se pueden seguir consultando con `getTaskResult`.
-   Si una `clientKey` lleva mucho tiempo sin usarse, el sistema le asigna una fecha de vencimiento para proteger tu cuenta y te envía un correo antes de que venza. Ese vencimiento no se puede modificar: genera de nuevo la Key principal (el saldo pasa a la nueva automáticamente) o crea otra `clientKey`, y actualiza tu programa.

## Saldo, límite de tareas simultáneas y pausa automática

-   **Saldo**: todas las `clientKey` descuentan del mismo saldo de la cuenta. Las recargas, los bonos VIP, las recompensas por referidos y la participación del desarrollador pertenecen a la cuenta, sin importar qué `clientKey` uses.
-   **Límite de tareas simultáneas**: se cuenta por cuenta; todas tus `clientKey` comparten el mismo tope. Consulta [Límite de tareas simultáneas y pausa automática](https://docs.yescaptcha.com/es/api/rate-limits.md).
-   **Pausa automática**: se cuenta por `clientKey`. Si una `clientKey` se pausa por demasiados errores, las demás no se ven afectadas.

## Códigos de error relacionados

| Código de error | Cuándo se devuelve |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | El límite que queda en el periodo actual no alcanza para esta tarea (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | La IP de la solicitud no está en la lista blanca de IP de esta `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/es/api/errors.md#ERROR_KEY_EXPIRED) | La `clientKey` ha vencido (`createTask`, `getBalance`) |

Ninguno de estos cobra puntos. Consulta [Códigos de error](https://docs.yescaptcha.com/es/api/errors.md) para saber qué hacer.