# Fehler und Ratenbegrenzung

Fehler der KolWrite-API werden als JSON-Antworten mit einem stabilen `code` geliefert, wann immer
der Client handeln kann.

```json
{
  "detail": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'jobs:write' scope",
    "required_scope": "jobs:write"
  }
}
```

## Häufige Status

| Status | Bedeutung |
|---|---|
| `400` | Ungültige Eingabe oder nicht unterstützte Optionskombination |
| `401` | Token fehlt, ist ungültig, abgelaufen oder widerrufen |
| `403` | Token ist gültig, aber es fehlt der Bereich oder der Routenzugriff |
| `404` | Ressource fehlt oder ist für den Token-Inhaber nicht sichtbar |
| `409` | Konflikt, meist ein Problem mit Idempotenz oder Zustandswechsel |
| `422` | Der Anfragekörper ist gültiges JSON, besteht die Prüfung aber nicht |
| `429` | Ratenbegrenzung oder Druck bei der Credit-Reservierung |
| `5xx` | Vorübergehender Fehler im KolWrite-Dienst |

## Hinweise zu Wiederholungen

Wiederholen Sie `429`, `502`, `503` und `504` mit exponentiellem Backoff und Jitter.
Verwenden Sie `Idempotency-Key` beim Erstellen von Jobs, damit Netzwerkwiederholungen nie
doppelte Jobs erzeugen. Wiederholen Sie `401`, `403` oder Validierungsfehler nicht, bis
Token oder Anfrage korrigiert sind.