Guide

Erreurs

Chaque erreur de l'API vokse renvoie une enveloppe JSON cohérente, avec un code stable lisible par une machine, un message lisible par un humain et des détails structurés optionnels. Construisez votre logique autour du code, affichez le message.

L'enveloppe d'erreur

Les réponses non-2xx adoptent cette structure. Le statut HTTP vous indique la classe ; error.code vous dit exactement ce qui s'est passé. details est un objet optionnel et traceId identifie la requête dans nos 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"  }}

Codes courants

Voici les codes que vous aurez le plus souvent à gérer :

`INVALID_REQUEST`	422	Le corps ou les paramètres de la requête n'ont pas passé la validation Zod. details.issues liste chaque champ fautif.
`UNAUTHORIZED`	401	En-tête Authorization manquant ou mal formé.
`SCOPE_DENIED`	403	La clé est valide mais ne possède pas le scope requis par cet endpoint.
`API_KEY_NOT_ALLOWED`	403	Cet endpoint est réservé aux sessions et ne peut pas être appelé avec une clé API.
`API_KEY_EXPIRED`	401	La clé a dépassé sa date d'expiration. Effectuez sa rotation.
`NOT_FOUND`	404	La ressource n'existe pas ou n'est pas visible pour ce foyer.
`IDEMPOTENCY_KEY_REUSED`	409	Un Idempotency-Key a été réutilisé avec un corps de requête différent.
`RATE_LIMITED`	429	Trop de requêtes. Ralentissez et réessayez après le délai indiqué par l'en-tête Retry-After.

Lire les détails

Pour INVALID_REQUEST, details.issues contient les issues Zod : une entrée par champ invalide, avec son chemin et son message. Traitez error.code comme le contrat et error.message comme un texte d'affichage susceptible de changer ; mentionnez le traceId lorsque vous contactez le support.