Leitfaden

Fehler

Jeder Fehler der vokse-API kommt im selben JSON-Format: ein stabiler, maschinenlesbarer Code, eine für Menschen verständliche Nachricht und optionale strukturierte Details. Entwickle gegen den Code, zeige die Nachricht an.

Das Fehlerformat

Nicht-2xx-Antworten haben diese Form. Der HTTP-Status verrät dir die Klasse, error.code sagt dir genau, was passiert ist. details ist ein optionales Objekt, und traceId identifiziert die Anfrage in unseren Logs.

json

{  "error": {    "code": "SCOPE_DENIED",    "message": "API key is missing required scopes: write:transactions",    "details": {      "requiredScopes": ["write:transactions"],      "grantedScopes": ["read:transactions"],      "missing": ["write:transactions"]    },    "traceId": "01J8MEB4W2Q0F7GXK3N5D8C1VZ"  }}

Gängige Codes

Diese Codes wirst du am ehesten behandeln:

`INVALID_REQUEST`	422	Der Request-Body oder die Query hat die Zod-Validierung nicht bestanden. details.issues listet jedes beanstandete Feld auf.
`UNAUTHORIZED`	401	Fehlender oder fehlerhafter Authorization-Header.
`SCOPE_DENIED`	403	Der Schlüssel ist gültig, besitzt aber nicht den Scope, den dieser Endpunkt erfordert.
`API_KEY_NOT_ALLOWED`	403	Dieser Endpunkt ist nur per Session aufrufbar und kann nicht mit einem API-Schlüssel verwendet werden.
`API_KEY_EXPIRED`	401	Der Schlüssel hat sein Ablaufdatum überschritten. Rotiere ihn.
`NOT_FOUND`	404	Die Ressource existiert nicht oder ist für diesen Haushalt nicht sichtbar.
`IDEMPOTENCY_KEY_REUSED`	409	Ein Idempotency-Key wurde mit einem anderen Request-Body wiederverwendet.
`RATE_LIMITED`	429	Zu viele Anfragen. Warte ab und versuche es nach der Zeit aus dem Retry-After-Header erneut.

Details lesen

Bei INVALID_REQUEST enthält details.issues die Zod-Issues: ein Eintrag pro ungültigem Feld, mit Pfad und Meldung. Behandle error.code als den Vertrag und error.message als Anzeigetext, der sich ändern kann; nenne die traceId, wenn du den Support kontaktierst.