Codes d'erreur

Réponses API ministry, embed et ERP : enveloppe { "code": "...", "message": "..." }. Messages API en anglais ; pivotez sur code.

Générique et auth

Code	HTTP	Signification
generic.bad_request	400	Requête mal formée
generic.unauthorized	401	Authentification requise ou clé invalide
generic.forbidden	403	Opération interdite pour ce scope
generic.not_found	404	Ressource introuvable
generic.conflict	409	Conflit d'état générique
generic.validation_failed	422	Corps ou paramètres invalides (ex. devise checkout non supportée)
generic.rate_limited	429	Rate limit (ex. 30/min create session)
generic.internal	500	Erreur interne
idempotency.conflict	409	Même Idempotency-Key, corps différent

Checkout ministry

Code	HTTP	Signification
checkout.not_found	404	Session inconnue
checkout.expired	422	Session expirée (TTL)
checkout.completed	409	Session déjà payée
checkout.session_open	409	Session ouverte existe pour cet order_id
checkout.not_paid	422	Session non payée (ex. receipt)
checkout.tenant_required	400	tenant_id requis avec clé plateforme
checkout.amount_invalid	422	Montant collecte invalide
checkout.amount_exceeds_balance	409	Montant supérieur au solde

Checkout embed

Code	HTTP	Signification
embed.origins_required	422	Origines embed non configurées
checkout.completion_token_not_found	404	Token invalide
checkout.completion_token_expired	410	Token expiré (~10 min)
checkout.completion_token_consumed	409	Token déjà utilisé (rejouer verify → idempotent 200 si déjà payé)

Connecteur et capacités ministry

Code	HTTP	Signification
connector.unavailable	503	Aucun connecteur MM disponible (agence possible)
capability.ministry_integrator_disabled	403	API ministry désactivée pour la régie
capability.cash_collection_disabled	403	Collecte agence désactivée
payment_ref.codes_required	422	Codes agence requis pour payment_ref

ERP intégration

Code	HTTP	Signification
erp.not_configured	404	ERP non configuré pour le tenant
erp.adapter_unavailable	400	Adaptateur ERP demandé indisponible
erp.connection_failed	503	Test connexion ou appel ERP en échec
capability.erp_integration_disabled	403	Intégration ERP désactivée
capability.citizen_portal_disabled	403	Portail citoyen désactivé
capability.bulk_disbursement_disabled	403	Disbursement masse désactivé

Portail citoyen (panier et dues)

Code	HTTP	Signification
citizen.cart_not_found	404	Panier introuvable
citizen.cart_empty	422	Panier vide
citizen.cart_not_open	422	Panier non modifiable
citizen.cart_currency_mismatch	422	Devises hétérogènes dans le panier
citizen.amount_exceeds_outstanding	422	Montant > solde ERP
citizen.amount_below_minimum	422	Montant < minimum ERP
citizen.amount_partial_not_allowed	422	Partial interdit sur la ligne
citizen.intent_already_pending	409	Intent paiement déjà en cours
citizen.link_not_active	404	Liaison citoyen-régie inactive

Disbursement

Code	HTTP	Signification
disbursement.reference_taken	409	batch_ref déjà importé
disbursement.invalid_transition	409	Transition batch invalide
disbursement.concurrent_state_change	409	État batch modifié ; rafraîchir
disbursement.batch.import_not_allowed	409	Import interdit dans cet état

Webhooks (configuration régie)

Codes lors de la gestion d'endpoints (pas sur votre handler ministry) :

Code	HTTP	Signification
webhook.url_missing	422	URL webhook absente
webhook.url_unsafe	422	URL webhook non autorisée
webhook.endpoint_not_subscribed	422	Endpoint non abonné à l'événement
webhook.platform_managed	409	Endpoints eGouv via Intégration eGouv, pas via routes application génériques

Côté votre endpoint webhook : répondre HTTP 2xx pour accepter ; 5xx seulement si retry souhaité.

Receipt

Code	HTTP	Signification
receipt.not_paid	422	Quittance non payée

Journal des modifications

Nouveaux codes publics documentés dans changelog.