# Fehler & Rate Limits

### Fehlerformat

Jede Fehlerantwort verwendet die gleiche JSON-Form und einen entsprechenden HTTP-Statuscode:

```json
{
  "statusCode": 403,
  "code": "FORBIDDEN",
  "message": "Missing required scope: govern:checkpoints:write"
}
```

| Feld | Beschreibung |
| ------------ | ------------------------------------------- |
| `statusCode` | Der HTTP-Statuscode, der im Body wiederholt wird. |
| `code` | Ein stabiler, maschinenlesbarer Fehlercode. |
| `message` | Eine menschenlesbare Beschreibung, sicher zu protokollieren. |

#### Statuscodes

| Status | Wenn es passiert |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request` | Ein erforderliches Feld fehlt oder ist ungültig - z.B. `action` an einem Kontrollpunkt ausgelassen wird oder `tool_name` weggelassen auf a `tool_call` Scan. |
| `401 Unauthorized` | Der API-Schlüssel fehlt, wird fehlgeformt, widerrufen oder von einer unzulässigen IP verwendet. |
| `403 Forbidden` | Der Schlüssel ist gültig, aber es fehlt der erforderliche Umfang. |
| `404 Not Found` | Die referenzierte Ressource (z. B. eine Checkpoint-ID) existiert in diesem Arbeitsbereich nicht. |
| `429 Too Many Requests` | Die Steuergrenze wurde überschritten. Ehre der `Retry-After` Header. |
| `500` | Ein unerwarteter Serverfehler. Die `message` ist generisch; versuchen Sie es mit Backoff. |

### Zinsbindungen

Die API erzwingt eine **Schiebefenster, pro Schlüssel** Grenzwert.

* **Standard:** 600 Anfragen pro Minute pro API-Schlüssel.
* **Antwort bei Überschreitung:** `429 Too Many Requests` mit einem `Retry-After` Header (Sekunden warten).

```
HTTP/1.1 429 Too Many Requests
Retry-After: 12
```

#### Pollen-Etikette

Wenn Sie einen Checkpoint mit `GET /v1/checkpoints/{id}`, halten Sie eine **Mindestens 1 Sekunde** zwischen Umfragen des gleichen Checkpoints - engere Umfragen werden abgelehnt. Bevorzugt den Long-Poll-Endpunkt `GET /v1/checkpoints/{id}/wait`, die die Verbindung offen hält und zurückkehrt, sobald sich der Zustand ändert, so dass Sie weit weniger Anfragen stellen.

### Idempotenz

Schreibe Endpunkte ()`POST /v1/checkpoints`, `POST /v1/secure/scan`Akzeptieren Sie eine optionale `Idempotency-Key` Header so Retries sind sicher:

```
Idempotency-Key: 4f1e9c2a-7b3d-4a1f-9c8e-2d6b0a5f1e33
```

Wiederverwendung des gleichen Schlüssels mit einem **unterschiedlich** Request Body wird abgelehnt - ein Schlüssel ist an die Nutzlast gebunden, mit der er zuerst gesehen wurde. Verwenden Sie eine neue UUID pro logischer Operation und verwenden Sie sie nur wieder, wenn Sie genau diese Operation wiederholen.