Erreurs

Toute erreur répond avec la même enveloppe JSON :

{ "error": { "code": "…", "messageFr": "…", "field": "…", "rule": "…", "erreurM": "…", "requestId": "…" } }

code est stable : un client se décide sur lui, jamais sur le message. messageFr est le message à montrer à l'usager. field, rule et erreurM ne sont présents que lorsqu'ils s'appliquent. requestId (aussi dans l'en-tête X-Request-Id) sert au support. Les réponses 429 et certaines 503 portent l'en-tête Retry-After, en secondes.

Code	Statut	Où	Cause	Remède
`VALIDATION_ERROR`	400	Toutes les routes qui lisent un corps ou des paramètres.	Une donnée est invalide : champ inconnu du calculateur, type ou borne non respectés, valeur hors des choix d'un `select`, champ obligatoire absent, ou combinaison refusée par une contrainte du formulaire. `field` nomme le champ fautif, `rule` la contrainte du formulaire et `erreurM` le code d'erreur bloquante de la DGFiP quand le refus en vient.	Corriger la valeur désignée par `field` ; les bornes et les choix admis se lisent dans `GET /v1/calculators/{slug}/schema`.
`MALFORMED_JSON`	400	Toutes les routes POST.	Le corps de la requête n'est pas un JSON valide.	Envoyer un document JSON bien formé.
`UNSUPPORTED_MEDIA_TYPE`	415	Toutes les routes POST sous `/v1`, sauf `/v1/auth/*`.	L'en-tête `Content-Type` n'annonce pas du JSON.	Envoyer l'en-tête `Content-Type: application/json`.
`PAYLOAD_TOO_LARGE`	413	Toutes les routes ; `POST /v1/recherches` pour une réponse enregistrée trop longue.	Le corps dépasse 100 Kio (ou la réponse à enregistrer dépasse 64 Kio une fois sérialisée).	Réduire le corps : ne transmettre que les cases renseignées.
`NOT_FOUND`	404	Routes qui nomment un calculateur, un module, une recherche enregistrée ou un objet de consentement.	La ressource nommée dans le chemin n'existe pas.	Lister les calculateurs par `GET /v1/calculators` et les modules par `GET /v1/modules`.
`HTTP_ERROR`	400	Toutes les routes.	Refus du cadre HTTP lui-même, sans cause plus précise ; le statut est celui de l'exception levée (400 le plus souvent, un autre statut 4xx possible).	Vérifier la méthode, le chemin et les en-têtes de la requête.
`ENGINE_ERROR`	422	Routes de calcul.	Le moteur a refusé de calculer une saisie pourtant bien formée.	Lire `messageFr`, qui dit la cause, et signaler le cas avec son `requestId` s'il paraît légitime.
`INTERNAL_ERROR`	500	Toutes les routes.	Erreur inattendue du serveur ; elle est journalisée.	Réessayer ; si l'erreur persiste, la signaler avec son `requestId`.
`RATE_LIMITED`	429	Routes POST de `/v1/calculators/`, `/v1/entrainement/`, `/v1/consentements` et l'assistant.	Trop de requêtes depuis la même adresse sur la fenêtre d'une minute.	Attendre le délai de l'en-tête `Retry-After` (en secondes) avant de réessayer.
`PDF_ACCOUNT_REQUIRED`	429	`POST /v1/calculators/{slug}/pdf`.	Le quota quotidien de déclarations pré-remplies gratuites est atteint.	Réessayer après le délai de `Retry-After`, ou se connecter à un compte.
`SERVICE_INDISPONIBLE`	502, 503, 504	`POST /v1/calculators/{slug}/pdf` et `GET /v1/calculators/{slug}/pdf-coverage` sur un serveur sans les PDF officiels.	Le serveur qui a reçu la requête ne détient pas les formulaires PDF officiels et n'a pas de relais configuré (503), ou le serveur relayé est injoignable (502) ou n'a pas répondu dans les 25 secondes (504).	Réessayer plus tard.
`ASSISTANT_UNAVAILABLE`	503	`POST /v1/assistant` et `POST /v1/assistant/stream`.	Les compteurs de l'assistant sont injoignables : il reste fermé plutôt que de répondre sans limite.	Réessayer après le délai de `Retry-After`.
`ASSISTANT_BUSY`	429	`POST /v1/assistant` et `POST /v1/assistant/stream`.	Une autre question de la même adresse est déjà en cours.	Attendre la réponse en cours avant d'en poser une nouvelle.
`ASSISTANT_ACCOUNT_REQUIRED`	429	`POST /v1/assistant` et `POST /v1/assistant/stream`.	Le nombre quotidien de questions gratuites traitées par un modèle est atteint.	Réessayer le lendemain, ou se connecter à un compte.
`ASSISTANT_BUDGET_EXHAUSTED`	503	`POST /v1/assistant` et `POST /v1/assistant/stream`.	Le budget quotidien ou mensuel de l'assistant est épuisé.	Réessayer après le délai de `Retry-After`.
`ASSISTANT_AVANCE_INDISPONIBLE`	503	`POST /v1/assistant` et `POST /v1/assistant/stream`.	Le lecteur déterministe n'a pas su traiter la demande et les niveaux suivants (modèle) ne sont pas configurés sur ce serveur.	Reformuler la situation simplement : situation de famille, enfants, revenus.
`ASSISTANT_ERROR`	200	`POST /v1/assistant/stream`, événement SSE `error` (le flux a déjà répondu 200).	L'assistant a échoué en cours de réponse.	Réessayer dans un instant ; le `requestId` de l'événement sert au support.
`ACCOUNTS_UNAVAILABLE`	503	Routes des comptes (`/v1/auth/`, `/v1/recherches`, `/v1/consentements`, `/v1/entrainement/`, `/v1/compte/*`).	Les comptes ne sont pas configurés sur ce serveur.	Réessayer plus tard.
`UNAUTHENTICATED`	401	Routes qui exigent un compte connecté (`/v1/recherches`, `GET /v1/consentements/{objet}`, `/v1/compte/export`).	Aucune session valide n'accompagne la requête.	Se connecter par `/v1/auth/*` et renvoyer le cookie de session.
`SAVED_SEARCHES_LIMIT`	409	`POST /v1/recherches`.	Le compte a atteint le nombre maximal de recherches enregistrées.	Supprimer une recherche enregistrée avant d'en ajouter une.