# Fehler und Ratenbegrenzungen
Source: https://nordvec.com/de/docs/guides/errors-and-rate-limits

Die eine Fehlerhülle, die jede fehlgeschlagene Anfrage zurückgibt, die Ratenbegrenzungs-Header und wie du einen Schreibvorgang sicher wiederholst.



Jeder Endpunkt schlägt auf die gleiche Weise fehl, daher behandelst du Fehler, Ratenlimits und Wiederholungsversuche einmal und verwendest diesen Code überall wieder, auch über [MCP](/docs/guides/mcp).

## Die Fehlerhülle [#die-fehlerhülle]

Jede nicht-2xx-Antwort ist ein JSON-Objekt:

```json
{
  "defined": false,
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests",
  "data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```

* `code` ist der HTTP-Level-Fehler, zum Beispiel `UNAUTHORIZED`, `FORBIDDEN`,
  `NOT_FOUND`, `BAD_REQUEST` oder `TOO_MANY_REQUESTS`.
* `data.reason` ist, falls vorhanden, ein genauerer maschinenlesbarer Grund wie
  `auth.key_not_found` oder `rate_limit.exceeded`. Verzweige darauf statt auf
  `message`, das für Menschen gedacht ist und sich ändern kann.
* `defined` ist `true`, wenn die Operation diesen Fehler in der
  [API-Referenz](/docs/api) auflistet, und `false` für Fehler, die jede Anfrage treffen können
  (Authentifizierung, Ratenlimits, eine unbekannte Route).
* Eine Validierungsfehlermeldung antwortet mit `BAD_REQUEST` und den Problemen in
  `data.formErrors` und `data.fieldErrors`.

Jede Antwort enthält außerdem eine `X-Request-ID`. Gib sie an, wenn du den Support kontaktierst,
damit wir diese genaue Anfrage finden können.

## Häufige Statuscodes [#häufige-statuscodes]

| Status | Code                    | Was zu tun ist                                                                           |
| ------ | ----------------------- | ---------------------------------------------------------------------------------------- |
| `400`  | `BAD_REQUEST`           | Korrigiere die Anfrage; `data.fieldErrors` benennt die Felder                            |
| `401`  | `UNAUTHORIZED`          | Sende einen gültigen Schlüssel oder eine gültige Session                                 |
| `403`  | `FORBIDDEN`             | Der Schlüssel hat nicht den benötigten Scope oder die benötigte Rolle für die Operation  |
| `404`  | `NOT_FOUND`             | Die Ressource existiert nicht oder du darfst sie nicht sehen                             |
| `409`  | `CONFLICT`              | Ein doppelter Schreibvorgang ist noch in Bearbeitung; wiederhole den Versuch kurzfristig |
| `413`  | `PAYLOAD_TOO_LARGE`     | Der Anfragekörper ist über 1 MB groß; teile einen Massen-Push in kleinere Chargen auf    |
| `422`  | `UNPROCESSABLE_CONTENT` | Die Anfrage ist korrekt formuliert, kann aber nicht angewendet werden                    |
| `429`  | `TOO_MANY_REQUESTS`     | Warte `Retry-After`, dann wiederhole den Versuch                                         |

## Ratenlimits [#ratenlimits]

Jede Antwort gibt das Limit an, gegen das sie gezählt wurde, in zwei Formen:

* die `X-RateLimit-*`-Header;
* die IETF-Strukturfelder `RateLimit` (Live-Zustand: `r` sind die verbleibenden Anfragen,
  `t` die Sekunden bis zum Zurücksetzen des Fensters) und `RateLimit-Policy`
  (das Kontingent: `q` ist das Limit, `w` das Fenster in Sekunden).

Eine `429` enthält außerdem `Retry-After` in Sekunden und `data.retryAfterMs`. Warte mindestens so lange,
bevor du die nächste Anfrage sendest; ein früherer Wiederholungsversuch wird gezählt und
abgelehnt.

## Schreibvorgänge sicher wiederholen [#schreibvorgänge-sicher-wiederholen]

Ein Schreibvorgang, der einen `Idempotency-Key`-Header in der
[API-Referenz](/docs/api) auflistet, kann wiederholt werden, ohne die Arbeit doppelt auszuführen. Sende
einen Schlüssel pro logischem Schreibvorgang und wiederhole denselben Schlüssel bei jedem Wiederholungsversuch:

* derselbe Schlüssel mit demselben Body innerhalb von 24 Stunden gibt die gespeicherte Antwort erneut aus;
* derselbe Schlüssel mit einem anderen Body wird mit `422` abgelehnt;
* ein Duplikat, das ankommt, während der erste Vorgang noch läuft, erhält `409`.

Ein Vorgang ohne diesen Header ist nicht idempotent, daher wiederhole ihn nur, wenn du sicher bist,
dass der erste Versuch nicht erfolgreich war.