# Fehlercodes

> Alle Fehlercodes der YesCaptcha API mit Bedeutung und Vorgehen: Anfrageformat, Konto und Guthaben, gleichzeitige Aufgaben und Pausierung, Aufgabenergebnis, Website-Parameter, Bilder, Proxy, Server. Anfragen, die einen Fehler zurückgeben, werden nicht berechnet.

Source: https://docs.yescaptcha.com/de/api/errors/ · Last verified: 2026-10-15

> This page was machine-translated from the Chinese version. If anything differs, the Chinese version prevails: https://docs.yescaptcha.com/zh/api/errors/

Bei einem Fehler gibt die API `errorId: 1` zurück. `errorCode` enthält den Fehlercode, `errorDescription` die Beschreibung als Text. Anfragen, die einen Fehler zurückgeben, verursachen keinen Punkteabzug: Tritt der Fehler schon beim Erstellen der Aufgabe auf, wird nichts abgezogen. Schlägt die Erkennung nach dem Erstellen fehl oder läuft sie in ein Timeout, erfolgt automatisch eine Punkteerstattung.

> **Tipp:** Werten Sie im Programm `errorCode` aus, nicht den Text von `errorDescription`. Die Textbeschreibung kann sich ändern.

```json
{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}
```

## Vorgehen bei Fehlern

1.  **Parameterfehler** (Anfrageformat, ClientKey, Aufgabentyp, Website-Parameter, Bilder) ändern sich durch erneutes Senden nicht. Korrigieren Sie zuerst die Anfrage.
2.  **Fehlgeschlagene Erkennung und Timeouts** (`ERROR_CAPTCHA_UNSOLVABLE`, `ERROR_TASK_TIMEOUT`): Sie können die Aufgabe neu erstellen.
3.  Beenden Sie nach einem Fehler die **regelmäßige Abfrage (Polling)** für diese `taskId`. Senden Sie dieselbe Anfrage nicht unverändert in hoher Frequenz erneut.
4.  Fehler mit der Kennzeichnung „zählt zur automatischen Pausierung“: Treten für denselben `clientKey` innerhalb einer Minute 100 davon auf, wird das Erstellen von Aufgaben für 5 Minuten pausiert. Fehler mit der Kennzeichnung „Cache“ zählen nicht mit, aber solange sie im Cache sind, geben gleiche Anfragen direkt den ursprünglichen Fehler zurück. Details: [Limit gleichzeitiger Aufgaben und automatische Pausierung](https://docs.yescaptcha.com/de/api/rate-limits.md).

## Alle Fehlercodes

### Anfrageformat

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_REQUIRED_FIELDS` | Ein Pflichtfeld fehlt (etwa `clientKey` oder `websiteURL` / `websiteKey` für den Aufgabentyp), oder der Request-Body ist kein JSON | Ergänzen Sie die fehlenden Felder gemäß der Seite des Aufgabentyps und senden Sie JSON per `POST` mit `Content-Type: application/json` |
| `ERROR_REQUEST_FORMATS` (Zählt zur Pausierung) | Der Request-Body ist kein gültiges JSON | Erzeugen Sie den Body mit einer JSON-Bibliothek statt durch Zusammensetzen von Strings; JSON darf keine `//`\-Kommentare enthalten |
| `ERROR_TASK_ABSENT` (Zählt zur Pausierung) | Das Feld `task` fehlt in einem `createTask`\-Aufruf | Legen Sie die Aufgabenparameter in einem `task`\-Objekt ab. Verwenden Sie bei Python requests `json=data`, nicht `data=data` |
| `ERROR_TASK_NOT_SUPPORTED` (Zählt zur Pausierung) | `task.type` ist falsch geschrieben, oder der Typ wurde eingestellt | Kopieren Sie den Typnamen aus "Aufgabentypen und Preise"; bei Namen wird zwischen Groß- und Kleinschreibung unterschieden |
| `ERROR_PAGE_NOT_FOUND` | Der angeforderte Pfad existiert nicht | Prüfen Sie die Endpoint-URL, z. B. `https://api.yescaptcha.com/createTask`; bei Methodennamen wird zwischen Groß- und Kleinschreibung unterschieden |
| `ERROR_BAD_REQUEST` | Die Anfrage kann nicht verarbeitet werden, meist wegen einer falschen HTTP-Methode (GET statt POST) oder ungültiger Parameterwerte | Senden Sie JSON per `POST` und prüfen Sie die Typen und Werte der Parameter |
| `ERROR_ILLEGAL_PARAMETERS` | Ein Parameterwert ist ungültig. Typisch für die Cloudflare-Prüfseite: `websiteURL` ist keine öffentliche URL mit `http://` / `https://`, `postData` ist kein Objekt oder `requiredCookies` ist kein Array von Strings (von createTask zurückgegeben, kein Punkteabzug); oder die Zieldomain konnte über den Proxy nicht aufgelöst werden (von getTaskResult zurückgegeben, automatische Punkteerstattung) | Korrigieren Sie den Wert gemäß der Parametertabelle auf der Seite des Aufgabentyps. Wenn die Domain nicht aufgelöst werden konnte, prüfen Sie die Schreibweise der URL und ob der Proxy die Website erreichen kann |

### Konto und Guthaben

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_KEY_DOES_NOT_EXIST` (Zählt zur Pausierung) | Der `clientKey` existiert nicht: Beim Kopieren wurden Zeichen hinzugefügt oder gingen verloren, oder der Schlüssel wurde im Dashboard zurückgesetzt | Kopieren Sie den Schlüssel erneut aus dem Dashboard auf yescaptcha.com, ohne Leerzeichen oder Zeilenumbrüche |
| `ERROR_KEY_EXPIRED` (Zählt zur Pausierung) | Der `clientKey` ist abgelaufen (wird von createTask und getBalance zurückgegeben, kein Punkteabzug). Entweder wurde er lange nicht verwendet und das System hat zum Schutz des Kontos ein Ablaufdatum gesetzt (vor dem Ablauf wird eine Erinnerung per E-Mail gesendet), oder das für diesen `clientKey` festgelegte Ablaufdatum ist überschritten | Melden Sie sich im Dashboard auf yescaptcha.com an. Wenn er nach langer Nichtverwendung abgelaufen ist, erzeugen Sie einen neuen `clientKey`; das Guthaben wird automatisch auf den neuen übertragen. Wenn ein Ablaufdatum festgelegt wurde, ändern Sie es oder verwenden Sie einen anderen `clientKey`. Aktualisieren Sie anschließend Ihr Programm mit dem neuen `clientKey` |
| `ERROR_KEY_IP_NOT_ALLOWED` | Für diesen `clientKey` ist eine IP-Zulassungsliste festgelegt, und die IP, von der die Anfrage stammt, steht nicht darauf (wird von createTask und getBalance zurückgegeben, ohne Punkteabzug, zählt nicht für die automatische Pausierung) | Melden Sie sich im Dashboard auf yescaptcha.com an und fügen Sie die öffentliche IP des Rechners, der die Anfragen sendet, zur Zulassungsliste dieses `clientKey` hinzu, oder verwenden Sie einen anderen `clientKey`. Wenn mehrere Rechner die API aufrufen, fügen Sie die öffentliche IP jedes einzelnen hinzu (gemeint ist die IP, die die YesCaptcha-API aufruft, nicht der Proxy in den Aufgabenparametern) |
| `ERROR_KEY_QUOTA_EXCEEDED` | Für diesen `clientKey` ist ein Ausgabenlimit festgelegt, und das verbleibende Limit des aktuellen Zeitraums reicht für den Punkteabzug dieser Aufgabe nicht aus (wird von createTask zurückgegeben, ohne Punkteabzug, zählt nicht für die automatische Pausierung). Das Limit rechnet mit den tatsächlich abgezogenen Punkten; Punkte, die bei fehlgeschlagenen Aufgaben oder Zeitüberschreitung erstattet werden, werden dem Limit wieder gutgeschrieben | Melden Sie sich im Dashboard auf yescaptcha.com an und erhöhen Sie das Limit dieses `clientKey`, warten Sie auf den nächsten Zeitraum (das Limit wird täglich, jeden Montag oder am 1. jedes Monats zurückgesetzt, jeweils nach Pekinger Zeit; ein einmaliges Limit wird nicht zurückgesetzt), oder verwenden Sie einen anderen `clientKey`. Mit `getBalance` erhalten Sie das verbleibende Limit dieses `clientKey` (`keyQuotaRemaining`) |
| `ERROR_ZERO_BALANCE` | Unzureichendes Guthaben. Das Guthaben muss über 10 Punkten liegen, um eine Aufgabe zu erstellen | Laden Sie Ihr Guthaben auf und versuchen Sie es erneut. Mit `getBalance` können Sie das Guthaben abfragen |

### Gleichzeitige Aufgaben und Pausierung

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_THREADS_MAXIMUM` (Zählt teilweise zur Pausierung) | Für das Konto sind zu viele Aufgaben dieses Typs gleichzeitig in Bearbeitung. `limit` in der Antwort ist das aktuelle Limit. Die Anfrage wurde nicht verarbeitet und es erfolgte kein Punkteabzug | Warten Sie, bis laufende Anfragen zurückkehren, oder warten Sie 1–2 Sekunden und versuchen Sie es erneut; begrenzen Sie die Anzahl gleichzeitig wartender Anfragen |
| `ERROR_IP_BLOCKED_5MIN` | Dieser `clientKey` hat in kurzer Zeit zu viele Fehler verursacht und wurde automatisch pausiert. `retryAfter` ist die verbleibende Zeit in Sekunden und `blockReason` ist der Fehler, der dies ausgelöst hat | Korrigieren Sie die Anfrage gemäß `blockReason` und warten Sie `retryAfter` Sekunden; Senden während der Pausierung verlängert diese nicht |
| `ERROR_NO_SLOT_AVAILABLE` | Der Erkennungsdienst ist vorübergehend überlastet. Wenn `createTask` diesen Fehler zurückgibt, wird kein Punkteabzug vorgenommen; eine Aufgabe, die zu lange in der Warteschlange war, liefert ihn auch bei `getTaskResult` zurück und wird automatisch mit einer Punkteerstattung ausgeglichen | Warten Sie einige Sekunden und erstellen Sie die Aufgabe erneut |

### Aufgaben und Ergebnisse

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_TASKID_INVALID` (Zählt zur Pausierung) | Die `taskId` existiert nicht, ist abgelaufen (Ergebnisse werden etwa 10 Minuten aufbewahrt), gehört zu einem anderen `clientKey` oder wurde auf dem anderen Endpoint erstellt | Beenden Sie die regelmäßige Abfrage (Polling) dieser Aufgabe. Fragen Sie mit demselben Endpoint und demselben `clientKey` ab, mit denen sie erstellt wurde |
| `ERROR_TASK_TIMEOUT` | Die Aufgabe wurde nicht rechtzeitig abgeschlossen (in der Regel 110 Sekunden); die Punkte wurden automatisch erstattet (Punkteerstattung) | Erstellen Sie eine neue Aufgabe; wenn weiterhin Zeitüberschreitungen auftreten, probieren Sie einen anderen Aufgabentyp für dasselbe Captcha |
| `ERROR_CAPTCHA_UNSOLVABLE` | Das Captcha konnte diesmal nicht gelöst werden; die Punkte wurden erstattet (Punkteerstattung). Dies zählt nicht zur automatischen Pausierung | Erstellen Sie eine neue Aufgabe. Wenn der Fehler weiterhin auftritt, prüfen Sie `websiteURL`, `websiteKey` und weitere Parameter oder probieren Sie einen anderen Aufgabentyp für dasselbe Captcha |
| `ERROR_SETTLEMENT_FAILED` (Zählt zur Pausierung) | Das Guthaben reichte bei der Abrechnung nicht aus, daher wurde kein Ergebnis zurückgegeben | Laden Sie Ihr Guthaben auf und erstellen Sie eine neue Aufgabe |
| `ERROR_NO_SUCH_CAPCHA_ID` | Die Aufgabe ist nicht mehr gültig | Beenden Sie die regelmäßige Abfrage (Polling) dieser Aufgabe und erstellen Sie eine neue |
| `ERROR_RECAPTCHA_TIMEOUT` | Die Lösung des Captchas hat das Zeitlimit überschritten; die Punkte wurden erstattet (Punkteerstattung) | Erstellen Sie eine neue Aufgabe |

### Parameter der Zielwebsite

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_RECAPTCHA_INVALID_SITEKEY` (Zwischengespeichert, keine Pausierung) | Der `websiteKey` ist ungültig | Suchen Sie den Sitekey erneut auf der Seite (siehe die Anleitungen zum Finden von Parametern). Identische Anfragen geben diesen Fehler während der Cache-Dauer direkt zurück, mit `cached: true` |
| `ERROR_RECAPTCHA_INVALID_DOMAIN` (Zwischengespeichert, keine Pausierung) | Die Domain von `websiteURL` passt nicht zum `websiteKey` | Setzen Sie `websiteURL` auf die Seite, auf der das Captcha angezeigt wird |
| `ERROR_INVALID_KEY_TYPE` (Zwischengespeichert, keine Pausierung) | Der Sitekey gehört zu einem anderen Captcha, z. B. ein v3-Key, der mit einem v2-Aufgabentyp verwendet wird | Bestimmen Sie zuerst den Captcha-Typ (siehe "Captcha-Typ bestimmen") und wählen Sie den passenden Aufgabentyp; für unsichtbares v2 setzen Sie `isInvisible` |
| `ERROR_DOMAIN_NOT_ALLOWED` (Zwischengespeichert, keine Pausierung) | Diese Website wird nicht unterstützt | Probieren Sie einen anderen Aufgabentyp für dasselbe Captcha oder wenden Sie sich an den Support |
| `ERROR_HIGH_DEMAND_DOMAIN` (Zählt zur Pausierung) | Diese Website wird nicht unterstützt | Senden Sie keine Aufgaben mehr für diese Website und wenden Sie sich an den Support |
| `ERROR_FAILED_LOADING_WIDGET` | Das Captcha konnte mit den angegebenen Parametern nicht geladen werden | Prüfen Sie `websiteURL` und `websiteKey`; bei Aufgabentypen mit eigenem Proxy prüfen Sie, ob der Proxy die Website erreichen kann |

### Bilder

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_ZERO_CAPTCHA_FILESIZE` (Zählt zur Pausierung) | Das Bild ist leer oder zu klein | Prüfen Sie, ob die Base64-Daten vollständig sind und kein Präfix `data:image/...;base64,` enthalten |
| `ERROR_TOO_BIG_CAPTCHA_FILESIZE` (Zählt zur Pausierung) | Das Bild ist zu groß | Komprimieren oder verkleinern Sie das Bild; der gesamte Request-Body darf 6 MB nicht überschreiten |
| `ERROR_IMAGE_TYPE_NOT_SUPPORTED` (Zählt zur Pausierung) | Das Bildformat wird nicht unterstützt, oder das Bild kann von diesem Aufgabentyp nicht verarbeitet werden. Ein einmaliges Auftreten pausiert den Schlüssel für 30 Minuten | Verwenden Sie JPG oder PNG und stellen Sie sicher, dass das Bild zum Aufgabentyp passt, z. B. benötigt die reCAPTCHA-Bilderkennung 100x100, 300x300 oder 450x450 |
| `ERROR_ILLEGAL_IMAGE` (Zählt zur Pausierung) | Die Bildgröße entspricht nicht den Anforderungen dieses Aufgabentyps | Passen Sie die Bildgröße wie auf der Seite des Aufgabentyps beschrieben an |
| `ERROR_PARSE_IMAGE_FAIL` | Das Bild konnte nicht dekodiert werden, häufig weil das Base64 unvollständig ist oder ein Präfix enthält | Prüfen Sie die Base64-Kodierung und entfernen Sie das Präfix `data:` sowie Zeilenumbrüche |
| `ERROR_UNKNOWN_QUESTION` | Die `question` ist falsch, oder diese Frage wird noch nicht unterstützt | Vergleichen Sie sie mit der Fragenliste auf der Seite des Aufgabentyps. Bei nicht unterstützten Fragen wenden Sie sich an den Support; neue Fragen werden in der Regel innerhalb von 3 Werktagen unterstützt |
| `ERROR_UNKNOW_450x450_QUESTION` | Diese Frage wird für 4x4-Bilder (450x450) noch nicht unterstützt | Laden Sie die Aufgabe auf der Seite neu, um eine andere Frage zu erhalten |

### Proxys

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_PROXY_CONNECT_REFUSED` | Der Proxy hat die Verbindung abgelehnt | Prüfen Sie Adresse, Port und Protokoll des Proxys und stellen Sie sicher, dass er externe Verbindungen akzeptiert (keine lokale Adresse wie 127.0.0.1) |
| `ERROR_PROXY_CONNECT_TIMEOUT` | Die Verbindung zum Proxy hat das Zeitlimit überschritten | Verwenden Sie einen zuverlässigeren Proxy |
| `ERROR_PROXY_READ_TIMEOUT` | Das Lesen über den Proxy hat das Zeitlimit überschritten | Verwenden Sie einen schnelleren Proxy |
| `ERROR_PROXY_BANNED` | Der Proxy ist nicht verfügbar, oder seine IP wird von der Zielwebsite blockiert | Verwenden Sie einen anderen Proxy |
| `ERROR_PROXY_INCORRECT` | Die Proxy-Parameter sind fehlerhaft formatiert | Prüfen Sie das Format von `proxyType`, `proxyAddress`, `proxyPort` (oder des `proxy`\-Strings) |
| `ERROR_PROXY_TRANSPARENT` | Der Proxy ist transparent und legt die echte IP offen | Verwenden Sie einen anonymen (Elite-)Proxy |
| `ERROR_PROXY_NOT_AUTHORISED` | Benutzername oder Passwort des Proxys sind falsch | Prüfen Sie `proxyLogin` und `proxyPassword` (oder die Zugangsdaten im `proxy`\-String) |
| `ERROR_PROXY_TLS_ERROR` | Der TLS-Handshake mit dem Proxy ist fehlgeschlagen, häufig weil `proxyType` falsch ist (z. B. https bei einem http-Proxy) | Prüfen Sie das Proxy-Protokoll |
| `ERROR_PROXY_CONNECTION_FAILED` | Verbindung zum Proxy-Server nicht möglich | Prüfen Sie Adresse und Port des Proxys und stellen Sie sicher, dass er funktioniert |

### Server

| Fehlercode | Bedeutung | Was zu tun ist |
| --- | --- | --- |
| `ERROR_SERVICE_UNAVALIABLE` | Der Dienst ist vorübergehend nicht verfügbar (der Code wird `UNAVALIABLE` geschrieben) | Versuchen Sie es später erneut; wenden Sie sich an den Support, falls der Fehler weiterhin auftritt |
| `ERROR_INTERNAL_SERVER_ERROR` | Ein interner Serverfehler ist aufgetreten | Versuchen Sie es später erneut; wenn der Fehler weiterhin auftritt, wenden Sie sich mit der `taskId` an den Support |
| `ERROR_UNKNOWN` | Ein nicht klassifizierter Fehler | Versuchen Sie es später erneut; wenn der Fehler weiterhin auftritt, wenden Sie sich mit der `taskId` an den Support |

## Zusätzliche Felder

Manche Fehlerantworten enthalten zusätzliche Felder:

| Feld | Auftreten bei | Beschreibung |
| --- | --- | --- |
| `retryAfter` | `ERROR_IP_BLOCKED_5MIN`, gecachte Fehler | Wie viele Sekunden noch zu warten sind |
| `blockReason` | `ERROR_IP_BLOCKED_5MIN` | Der Fehlercode, der die Pausierung ausgelöst hat |
| `blockDetail` | `ERROR_IP_BLOCKED_5MIN` | Typ, URL und sitekey der Anfragen, die die Pausierung ausgelöst haben, zur leichteren Eingrenzung |
| `cached` | gecachte Fehler | `true` bedeutet, dass es sich um ein gecachtes Ergebnis handelt und nichts erkannt wurde |
| `badRequest` | gecachte Fehler | Die Parameter, die den Cache getroffen haben |
| `limit` | `ERROR_THREADS_MAXIMUM` | Ihr aktuelles Limit gleichzeitiger Aufgaben |

Die Sprachregeln für `errorDescription` finden Sie unter [Anfrage und Antwort](https://docs.yescaptcha.com/de/api/overview.md).