# Mehrere ClientKeys: Limit, IP-Whitelist und Ablaufdatum

> Ein YesCaptcha-Konto kann bis zu 20 ClientKeys haben, die alle vom selben Konto-Guthaben abbuchen. Jeder kann ein eigenes Ausgabenlimit (pro Tag, Woche oder Monat oder einmalig, Zurücksetzung nach Pekinger Zeit), eine IP-Whitelist und ein Ablaufdatum haben, wirksam innerhalb weniger Sekunden.

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

Ein YesCaptcha-Konto kann bis zu 20 `clientKey` haben (einschließlich des ursprünglichen). Sie verwalten sie im [yescaptcha.com](https://yescaptcha.com/security)\-Dashboard auf der Seite „Schlüssel & Sicherheit“. Jeder `clientKey` kann Aufgaben erstellen und das Guthaben abfragen, und alle buchen vom selben Konto-Guthaben ab. Jeder kann ein eigenes Limit, eine eigene IP-Whitelist und ein eigenes Ablaufdatum haben; Änderungen wirken innerhalb weniger Sekunden.

Typische Einsatzfälle: getrennte Keys für Test- und Produktivumgebung oder für verschiedene Projekte; Keys an eigene Kunden oder Partner weitergeben, jeweils mit eigenem Limit; und wenn ein `clientKey` offengelegt wird, löschen Sie nur diesen, ohne andere Programme zu beeinträchtigen.

## Haupt-Key und Sub-Keys

|  | Haupt-Key | Sub-Key |
| --- | --- | --- |
| Was es ist | Der ursprüngliche `clientKey`, einer pro Konto | Zusätzlich zum Haupt-Key angelegt, bis zu 19 |
| Limit, IP-Whitelist, Ablaufdatum | Können gesetzt werden | Können gesetzt werden |
| Zurücksetzen | Ja: der alte wird sofort ungültig, das Guthaben wechselt zum neuen | Nein; löschen und einen neuen anlegen |
| Löschen | Nein | Ja: wird innerhalb weniger Sekunden ungültig und lässt sich nicht wiederherstellen |

-   Alle haben dasselbe Format: Die ersten 40 Zeichen sind der geheime Schlüssel, danach folgt Ihre Benutzer-ID.
-   Das Zurücksetzen des Haupt-Keys betrifft die Sub-Keys nicht.
-   Mit welchem `clientKey` Sie Aufgaben erstellen oder das Guthaben abfragen, die API und die Antworten sind gleich; es kommen nur die Prüfungen von Limit, IP-Whitelist und Ablaufdatum hinzu.

## ClientKey anlegen

1.  Melden Sie sich bei [yescaptcha.com](https://yescaptcha.com/) an und öffnen Sie die Seite „Schlüssel & Sicherheit“ ([yescaptcha.com/security](https://yescaptcha.com/security)).
2.  Klicken Sie unter „Alle Keys“ auf „Neuer Sub-Key“. Name (bis zu 40 Zeichen), Limit, IP-Whitelist und Ablaufdatum sind optional und können später geändert werden.
3.  Bestätigen Sie Ihre Identität erneut, wenn Sie dazu aufgefordert werden. Anlegen, Ändern und Löschen erfordern dies jeweils.
4.  Kopieren Sie den vollständigen `clientKey` und tragen Sie ihn in Ihr Programm ein. Sie können ihn später über das Augen-Symbol in der Liste erneut anzeigen.

> **Hinweis:** Anlegen, Ändern und Löschen wirken innerhalb weniger Sekunden. Ein Aufruf direkt nach dem Anlegen kann `ERROR_KEY_DOES_NOT_EXIST` zurückgeben; warten Sie einige Sekunden und versuchen Sie es erneut. In den ersten Sekunden nach dem Löschen oder Verschärfen von Einstellungen können bereits gesendete Anfragen noch mit den alten Einstellungen verarbeitet werden.

## Limit

Ein Limit begrenzt, wie viele Punkte ein `clientKey` pro Zeitraum höchstens ausgeben darf (1,000 Punkte = ¥1). Es kann zwischen 1 und 10,000,000,000 Punkten liegen. Es gibt vier Zeiträume, die nach Pekinger Zeit (UTC+8) zurückgesetzt werden:

| Zeitraum | Zurücksetzung |
| --- | --- |
| Pro Tag | Jeden Tag um 00:00 Uhr |
| Pro Woche | Jeden Montag um 00:00 Uhr |
| Pro Monat | Am 1. jedes Monats um 00:00 Uhr |
| Einmaliger Gesamtbetrag | Nie. Ist er aufgebraucht, kann dieser `clientKey` keine Aufgaben mehr erstellen; erhöhen Sie das Limit, um ihn weiter zu nutzen |

-   Gezählt werden die tatsächlich abgezogenen Punkte: Punkte, die bei fehlgeschlagenen Aufgaben oder Zeitüberschreitung erstattet werden, werden auch dem Limit wieder gutgeschrieben.
-   Reicht der Rest des Limits im aktuellen Zeitraum für den Punkteabzug einer Aufgabe nicht aus, gibt `createTask` [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) zurück. Es werden keine Punkte abgezogen, und es zählt nicht für die [automatische Pausierung](https://docs.yescaptcha.com/de/api/rate-limits.md).
-   In der Liste im Dashboard sehen Sie, wie viel jeder `clientKey` im aktuellen Zeitraum verbraucht hat und wann er das nächste Mal zurückgesetzt wird.
-   Ein Limit ist kein eigenes Guthaben: Alle `clientKey` buchen vom selben Konto-Guthaben ab, und ist das Konto-Guthaben aufgebraucht, erhalten Sie wie gewohnt `ERROR_ZERO_BALANCE`.

Wenn Sie [`getBalance`](https://docs.yescaptcha.com/de/api/get-balance.md) mit einem `clientKey` aufrufen, für den ein Limit gesetzt ist, ist `balance` der kleinere Wert aus Konto-Guthaben und Rest-Limit des aktuellen Zeitraums, und es gibt zusätzlich das Feld `keyQuotaRemaining` (verbleibendes Limit, in Punkten). Ein `clientKey` ohne Limit enthält dieses Feld nicht, die Antwort bleibt wie bisher.

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

## IP-Whitelist

Ein `clientKey` mit IP-Whitelist funktioniert nur für Anfragen, die von den IPs in der Liste gesendet werden. Leer bedeutet keine Einschränkung.

-   Tragen Sie die **öffentliche IP des Rechners ein, der die YesCaptcha-API aufruft** (die ausgehende IP), nicht den Proxy aus den Aufgabenparametern. Wenn mehrere Rechner die API aufrufen, tragen Sie die öffentliche IP jedes einzelnen ein.
-   Eine IPv4- oder IPv6-Adresse oder ein CIDR-Bereich pro Zeile, bis zu 50 Einträge. Eine einzelne Adresse erlaubt nur diese eine IP.
-   Schreiben Sie Bereiche als Netzwerkadresse: `203.0.113.0/24` ist zulässig, `203.0.113.5/24` nicht (die Host-Bits sind nicht 0).

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

-   Liegt die IP der Anfrage nicht in der Liste, geben `createTask` und `getBalance` [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) zurück. Es werden keine Punkte abgezogen, und es zählt nicht für die automatische Pausierung.
-   Wenn sich Ihre ausgehende IP ändert (Heim-Breitband, Cloud-Funktionen, rotierende Ausgangs-IPs), setzen Sie keine Whitelist oder tragen Sie den gesamten Bereich ein.

## Ablaufdatum

-   Jeder `clientKey` (auch der Haupt-Key) kann ein Ablaufdatum haben, das innerhalb der nächsten zehn Jahre liegen muss. Sie können es jederzeit ändern oder entfernen.
-   Nach dem Ablauf geben `createTask` und `getBalance` mit diesem Key [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_EXPIRED) zurück; es werden keine Punkte abgezogen. Bereits erstellte Aufgaben können weiterhin mit `getTaskResult` abgeholt werden.
-   Wird ein `clientKey` lange nicht verwendet, setzt das System zum Schutz Ihres Kontos ein Ablaufdatum und erinnert Sie vor Ablauf per E-Mail. Dieses Ablaufdatum lässt sich nicht ändern: Erzeugen Sie einen neuen Haupt-Key (das Guthaben wechselt automatisch zum neuen) oder legen Sie einen neuen `clientKey` an und aktualisieren Sie dann Ihr Programm.

## Guthaben, Limit gleichzeitiger Aufgaben und automatische Pausierung

-   **Guthaben**: Alle `clientKey` buchen vom selben Konto-Guthaben ab. Aufladungen, VIP-Bonus, Empfehlungsprämien und Entwicklerbeteiligung gehören zum Konto, unabhängig davon, welchen `clientKey` Sie verwenden.
-   **Limit gleichzeitiger Aufgaben**: gilt pro Konto; alle `clientKey` teilen sich dasselbe Limit. Siehe [Limit gleichzeitiger Aufgaben und automatische Pausierung](https://docs.yescaptcha.com/de/api/rate-limits.md).
-   **Automatische Pausierung**: gilt pro `clientKey`. Wird ein `clientKey` wegen zu vieler Fehler pausiert, sind die anderen nicht betroffen.

## Zugehörige Fehlercodes

| Fehlercode | Wann er zurückgegeben wird |
| --- | --- |
| [`ERROR_KEY_QUOTA_EXCEEDED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_QUOTA_EXCEEDED) | Der Rest des Limits im aktuellen Zeitraum reicht für diese Aufgabe nicht aus (`createTask`) |
| [`ERROR_KEY_IP_NOT_ALLOWED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_IP_NOT_ALLOWED) | Die IP der Anfrage steht nicht in der IP-Whitelist dieses `clientKey` (`createTask`, `getBalance`) |
| [`ERROR_KEY_EXPIRED`](https://docs.yescaptcha.com/de/api/errors.md#ERROR_KEY_EXPIRED) | Der `clientKey` ist abgelaufen (`createTask`, `getBalance`) |

Bei keinem von diesen werden Punkte abgezogen. Was zu tun ist, steht unter [Fehlercodes](https://docs.yescaptcha.com/de/api/errors.md).