# Anfragen und Antworten

> Allgemeine Konventionen der YesCaptcha API: POST mit JSON, Authentifizierung per clientKey, Antwortformat mit errorId, synchrone und asynchrone Aufgaben, Abfrage alle 5 Sekunden, Timeout nach 110 Sekunden, Ergebnisse etwa 10 Minuten gespeichert, Sprache der Hinweise nach Accept-Language.

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

Alle Methoden werden per HTTPS `POST` mit JSON aufgerufen (nur `/useragent` ist ein `GET`), authentifizieren sich mit dem `clientKey` im Request-Body und antworten mit JSON: `errorId` 0 bedeutet Erfolg, 1 bedeutet Fehler mit einem `errorCode`. Ein Captcha zu lösen erfordert zwei Schritte: `createTask` erstellt die Aufgabe, `getTaskResult` wird alle 5 Sekunden nach dem Ergebnis abgefragt. Synchrone Typen liefern das Ergebnis direkt in `createTask`.

## Anfrage

```bash
curl -s https://api.yescaptcha.com/createTask \
  -H 'Content-Type: application/json' \
  -d '{"clientKey": "YOUR_CLIENT_KEY", "task": {"type": "ImageToTextTaskOcrBase", "body": "BASE64_IMAGE"}}'
```

-   Endpoint: `https://api.yescaptcha.com` (global) oder `https://cn.yescaptcha.com` (China), siehe [Zugangsadressen](https://docs.yescaptcha.com/de/getting-started/endpoints.md).
-   Der Body ist JSON, wird mit dem Header `Content-Type: application/json` gesendet und darf höchstens 6 MB groß sein. JSON darf keine Kommentare enthalten.
-   Jede Anfrage muss `clientKey` enthalten. Kopieren Sie den im Dashboard angezeigten Wert vollständig.

> **Achtung:** Verwenden Sie bei Python requests `json=data`, nicht `data=data`. Letzteres sendet ein Formular und liefert `ERROR_TASK_ABSENT` oder `ERROR_REQUIRED_FIELDS`.

## Antwort

Erfolg:

```json
{
  "errorId": 0,
  "taskId": "61138bb6-19fb-11ec-a9c8-0242ac110006"
}
```

Fehler:

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

| Feld | Beschreibung |
| --- | --- |
| `errorId` | 0 Erfolg, 1 Fehler |
| `errorCode` | Fehlercode im Fehlerfall; Bedeutung und Lösung siehe [Fehlercodes](https://docs.yescaptcha.com/de/api/errors.md) |
| `errorDescription` | Textbeschreibung der Fehlerursache |
| `taskId` | Aufgaben-ID |
| `status` | `processing` (in Bearbeitung) oder `ready` (fertig) |
| `solution` | Erkennungsergebnis; die Felder hängen vom Aufgabentyp ab, siehe die Seiten der einzelnen Aufgabentypen |

Werten Sie `errorId` und `errorCode` aus, nicht den Text von `errorDescription`; er kann sich ändern.

## Synchron und asynchron

|  | Asynchron | Synchron |
| --- | --- | --- |
| Welche Typen | Typen, die ein Token zurückgeben (reCAPTCHA, hCaptcha, Turnstile, FunCaptcha), Cloudflare-Prüfseite, `ImageToTextTask`, `ImageToTextTaskM1` | Bilderkennung (Namen enden auf `Classification`), `ImageToTextTaskOcrBase`, `ImageToTextTaskMuggle` |
| `createTask` liefert | `taskId` | `status: "ready"` und `solution` |
| Ergebnis abrufen | `getTaskResult` alle 5 Sekunden aufrufen | Keine weitere Abfrage nötig |

Welcher Modus für welchen Typ gilt, steht in der Spalte „Rückgabeart“ unter [Aufgabentypen und Preise](https://docs.yescaptcha.com/de/tasks.md).

## Regelmäßige Abfrage (Polling)

1.  Warten Sie nach der `taskId` aus `createTask` 5 Sekunden und rufen Sie dann `getTaskResult` auf.
2.  Bei `status: "processing"` warten Sie weitere 5 Sekunden und versuchen es erneut; bei `status: "ready"` steht das Ergebnis in `solution`.
3.  Bei `errorId: 1` beenden Sie die Abfrage dieser Aufgabe und behandeln den `errorCode`.

-   Wiederholte Abfragen derselben `taskId` innerhalb von 5 Sekunden liefern sofort `processing`; häufigeres Abfragen liefert das Ergebnis nicht schneller.
-   Eine Aufgabe wird in der Regel höchstens 110 Sekunden bearbeitet (bei wenigen Typen 180 bis 220 Sekunden); danach wird `ERROR_TASK_TIMEOUT` zurückgegeben und die Punkte werden automatisch erstattet (Punkteerstattung).
-   Ergebnisse werden auf dem Server etwa 10 Minuten gespeichert; danach ist die `taskId` ungültig und Abfragen liefern `ERROR_TASKID_INVALID`.
-   Abfragen von Ergebnissen kosten keine Punkte; nur das Erstellen einer Aufgabe führt zu einem Punkteabzug.

## Sprache der Hinweise

Bei Hinweisen zu automatischer Pausierung, zwischengespeicherten ungültigen Parametern und Abbruch der Abfrage richtet sich `errorDescription` nach dem Request-Header `Accept-Language`: Beginnt er mit `zh`, wird Chinesisch zurückgegeben, bei jeder anderen Sprache Englisch, ohne diesen Header beides. Die Beschreibungen anderer Fehlercodes sind nicht betroffen.

## Nächste Schritte

-   [createTask: Aufgabe erstellen](https://docs.yescaptcha.com/de/api/create-task.md)
-   [getTaskResult: Ergebnis abrufen](https://docs.yescaptcha.com/de/api/get-task-result.md)
-   [Limit gleichzeitiger Aufgaben und automatische Pausierung](https://docs.yescaptcha.com/de/api/rate-limits.md): Bei zu vielen Fehlern wird Ihr Zugang für einige Minuten pausiert