> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehler

> Der Fehlerumschlag, alle Codes der API und was sich zu wiederholen lohnt.

Fehler teilen sich einen gemeinsamen Umschlag:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "payload.prompt", "message": "payload.prompt or payload.query is required" }],
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

`code` ist stabil und für Verzweigungen geeignet. `message` ist für Menschen gedacht und kann sich ändern. `details`
ist vorhanden, wenn wir das fehlerhafte Feld benennen können.

## Codes

| Code | Status | Bedeutung | Wiederholen? |
| - | - | - | - |
| `MISSING_API_KEY` | 401 | Bearer-Token fehlt oder ist falsch. | Nein: Schlüssel korrigieren |
| `VALIDATION_ERROR` | 400 | Fehlerhafter Body, unbekannter `taskType` oder weder `payload.prompt` noch `payload.query` vorhanden. | Nein: Anfrage korrigieren |
| `REGION_UNSUPPORTED` | 422 | Diese Engine kann das angefragte `country` grundsätzlich nicht bedienen. | Nein: andere Engine oder Region wählen |
| `REGION_UNAVAILABLE` | 422 | Für das angefragte `country` ist auf dieser Engine derzeit keine Kapazität frei. | Später, wenn Kapazität zurück ist |
| `RESOURCE_ALREADY_EXISTS` | 409 | Doppelter `idempotencyKey` am Einzel-Endpunkt. | Nein: Der Task existiert bereits |
| `PAYLOAD_TOO_LARGE` | 413 | Batch-Body größer als 8 MB. | Nein: kleinere Teile senden |
| `RESOURCE_NOT_FOUND` | 404 | Unbekannte Task-id, oder der Task hat das 24-stündige öffentliche Polling-Fenster überschritten. | Nein |
| `ENQUEUE_ERROR` | — | Fehler eines einzelnen Eintrags in einem Batch (z. B. ein kurzes Datenbankproblem auf einer Spur). Erscheint in `results[].error`, nie als HTTP-Status. | Ja |

<Note>
  `400` steht für eine Anfrage, die wir nicht parsen oder verstehen können. `422` ist Anfragen vorbehalten, die
  einwandfrei geformt sind, aber für die angefragte Region nicht bedient werden können. Eine Verzweigung nach
  `error.code` ist beständiger als nach dem Status.
</Note>

## Ablehnungen wegen der Region

Beide Regionscodes werden **vor** dem Einreihen entschieden. Sie erfahren es sofort, statt zuzusehen, wie ein Task
alle Wiederholungen aufbraucht und mit einem Fehler scheitert, der nur das Symptom zeigt.

`REGION_UNSUPPORTED` ist dauerhaft: Diese Engine kann das angefragte Land nicht bedienen.

```json theme={null}
{
  "success": false,
  "error": {
    "code": "REGION_UNSUPPORTED",
    "message": "CHATGPT cannot be served for country='CN': no proxy vendor has exit supply in CN. This is a permanent capability gap, not a transient one — retrying will not help. GOOGLE and AIMODE are unaffected by exit-IP limits and remain available for this country.",
    "details": { "taskType": "CHATGPT", "country": "CN", "cause": "no_proxy_route", "retryable": false },
    "timestamp": "2026-07-09T04:12:00.000Z"
  }
}
```

Siehe [die Tabelle der nicht bedienbaren Kombinationen](/de/engines/capacity).

`REGION_UNAVAILABLE` ist vorübergehend: Die Route existiert, aber gerade kann nichts sie bedienen. Fragen Sie
[`GET /capacity`](/de/api-reference/capacity) ab, um zu sehen, was jede Region derzeit bedienen kann.

## Batch-Fehler gelten pro Eintrag

Ein wohlgeformter Batch liefert immer `200`, auch wenn jeder Task darin fehlschlägt. Der HTTP-Status beschreibt die
*Anfrage*, `results[].success` jeden einzelnen *Task*.

```json theme={null}
{
  "success": true,
  "summary": { "total": 3, "succeeded": 2, "failed": 1 },
  "results": [
    { "success": true,  "index": 0, "task": { "...": "..." } },
    { "success": false, "index": 1, "error": { "code": "REGION_UNAVAILABLE", "message": "..." } },
    { "success": true,  "index": 2, "task": { "...": "..." } }
  ]
}
```

Nur eine insgesamt fehlerhafte Anfrage (kein JSON, kein Array, leer, über 500 Einträge, über 8 MB oder nicht
autorisiert) führt zu einem 4xx für den Batch selbst.

<Note>
  Ein Batch-Eintrag kann mit `REGION_UNAVAILABLE` oder `ENQUEUE_ERROR` fehlschlagen. Keiner der beiden steht im Enum
  der Fehler pro Eintrag des asynchronen Task-Vertrags, den diese API umsetzt. Beide sind Ergänzungen, kein Ersatz:
  `VALIDATION_ERROR` und `RESOURCE_ALREADY_EXISTS` bleiben unverändert.
</Note>

## Fehler auf Task-Ebene

Ein Task, der *nach* dem Einreihen fehlschlägt, erzeugt überhaupt keinen HTTP-Fehler. Sie erfahren davon über den Endstatus:

```json theme={null}
{
  "success": true,
  "task": { "id": "8f2c1e40-...", "status": "FAILED", "...": "..." },
  "credits": { "creditsToCharge": 0, "creditsCharged": 0 },
  "error": "ENGINE_TIMEOUT: The engine did not answer before the task deadline."
}
```

Beachten Sie den Formunterschied: Dieses `error` auf oberster Ebene ist ein **String**, nicht das Objekt
`{code, message, timestamp}` der Fehler auf Anfrageebene. Es beginnt mit einem Code, gefolgt von einem festen Satz
für diesen Code; verzweigen Sie also anhand des Codes: `ENGINE_TIMEOUT`, `ENGINE_NO_RESULT`, `ENGINE_FAILED` oder
`NO_IP_AVAILABLE` und `NO_ACCOUNT_AVAILABLE`, wenn nicht rechtzeitig Kapazität frei wurde (ein späterer neuer Versuch
funktioniert meist). `BAD_PAYLOAD` und `PAGE_UNAVAILABLE` (eine Naver-Seite, die sich nicht anonym lesen lässt)
behalten eine Meldung, die sagt, was zu ändern ist. Derselbe Task stellt einen Webhook mit `task.status === "FAILED"` zu.