Fehler & Rate Limits

Fehlerformat#

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

{
  "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/scanAkzeptieren 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.