Errors

Every error answers with the same JSON envelope:

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

code is stable: a client decides on it, never on the message. messageFr is the message to show to the user, in French: the API has no English error messages yet. field, rule and erreurM are present only when they apply. requestId (also in the X-Request-Id header) is used by support. 429 responses and some 503 responses carry the Retry-After header, in seconds.

Code	Status	Where	Cause	Remedy
`VALIDATION_ERROR`	400	Every route that reads a body or parameters.	A value is invalid: field unknown to the calculator, type or bound not met, value outside the choices of a `select`, required field missing, or combination refused by a constraint of the form. `field` names the faulty field, `rule` the constraint of the form and `erreurM` the DGFiP blocking error code when the refusal comes from it.	Correct the value named by `field`; bounds and allowed choices are given by `GET /v1/calculators/{slug}/schema`.
`MALFORMED_JSON`	400	Every POST route.	The request body is not valid JSON.	Send a well-formed JSON document.
`UNSUPPORTED_MEDIA_TYPE`	415	Every POST route under `/v1`, except `/v1/auth/*`.	The `Content-Type` header does not announce JSON.	Send the header `Content-Type: application/json`.
`PAYLOAD_TOO_LARGE`	413	Every route; `POST /v1/recherches` for a saved answer that is too long.	The body exceeds 100 KiB (or the answer to save exceeds 64 KiB once serialised).	Reduce the body: send only the boxes that are filled in.
`NOT_FOUND`	404	Routes that name a calculator, a module, a saved search or a consent subject.	The resource named in the path does not exist.	List the calculators with `GET /v1/calculators` and the modules with `GET /v1/modules`.
`HTTP_ERROR`	400	Every route.	Refusal by the HTTP framework itself, with no more precise cause; the status is that of the exception raised (400 in most cases, another 4xx status is possible).	Check the method, the path and the headers of the request.
`ENGINE_ERROR`	422	Calculation routes.	The engine refused to calculate an input that is nonetheless well formed.	Read `messageFr`, which states the cause, and report the case with its `requestId` if it looks legitimate.
`INTERNAL_ERROR`	500	Every route.	Unexpected server error; it is logged.	Try again; if the error persists, report it with its `requestId`.
`RATE_LIMITED`	429	POST routes of `/v1/calculators/`, `/v1/entrainement/`, `/v1/consentements` and the assistant.	Too many requests from the same address within the one-minute window.	Wait for the delay given by the `Retry-After` header (in seconds) before trying again.
`PDF_ACCOUNT_REQUIRED`	429	`POST /v1/calculators/{slug}/pdf`.	The daily quota of free pre-filled returns has been reached.	Try again after the `Retry-After` delay, or sign in to an account.
`SERVICE_INDISPONIBLE`	502, 503, 504	`POST /v1/calculators/{slug}/pdf` and `GET /v1/calculators/{slug}/pdf-coverage` on a server without the official PDF forms.	The server that received the request does not hold the official PDF forms and has no relay configured (503), or the relayed server is unreachable (502) or did not answer within 25 seconds (504).	Try again later.
`ASSISTANT_UNAVAILABLE`	503	`POST /v1/assistant` and `POST /v1/assistant/stream`.	The assistant's counters are unreachable: it stays closed rather than answer without a limit.	Try again after the `Retry-After` delay.
`ASSISTANT_BUSY`	429	`POST /v1/assistant` and `POST /v1/assistant/stream`.	Another question from the same address is already in progress.	Wait for the current answer before asking a new question.
`ASSISTANT_ACCOUNT_REQUIRED`	429	`POST /v1/assistant` and `POST /v1/assistant/stream`.	The daily number of free questions handled by a model has been reached.	Try again the next day, or sign in to an account.
`ASSISTANT_BUDGET_EXHAUSTED`	503	`POST /v1/assistant` and `POST /v1/assistant/stream`.	The daily or monthly budget of the assistant is exhausted.	Try again after the `Retry-After` delay.
`ASSISTANT_AVANCE_INDISPONIBLE`	503	`POST /v1/assistant` and `POST /v1/assistant/stream`.	The deterministic reader could not handle the request and the next levels (model) are not configured on this server.	Describe the situation simply: family situation, children, income.
`ASSISTANT_ERROR`	200	`POST /v1/assistant/stream`, SSE event `error` (the stream has already answered 200).	The assistant failed while answering.	Try again in a moment; the `requestId` of the event is used by support.
`ACCOUNTS_UNAVAILABLE`	503	Account routes (`/v1/auth/`, `/v1/recherches`, `/v1/consentements`, `/v1/entrainement/`, `/v1/compte/*`).	Accounts are not configured on this server.	Try again later.
`UNAUTHENTICATED`	401	Routes that require a signed-in account (`/v1/recherches`, `GET /v1/consentements/{objet}`, `/v1/compte/export`).	No valid session comes with the request.	Sign in through `/v1/auth/*` and send the session cookie back.
`SAVED_SEARCHES_LIMIT`	409	`POST /v1/recherches`.	The account has reached the maximum number of saved searches.	Delete a saved search before adding a new one.