Erreurs et codes de statut

Traitez les erreurs par statut HTTP, code structuré et x-request-id, sans journaliser identifiants ou contenu des demandes.

Statut	Signification	Action du client
`400`	Requête invalide	Corriger les données ; ne pas réessayer sans changement.
`401`	Échec d’authentification	Renouveler ou remplacer le jeton.
`403`	Fonction ou forfait refusé	Vérifier les droits et le modèle.
`404`	Route ou ressource absente	Vérifier le chemin `/v1` et l’identifiant.
`429`	Limite atteinte	Respecter l’attente et réduire la concurrence.
`5xx`	Échec du service	Réessayer seulement le travail sûr avec attente limitée et variation aléatoire.

Les routes inconnues renvoient NOT_FOUND ; la validation, VALIDATION_ERROR ; les erreurs imprévues, INTERNAL_ERROR. Les messages fournisseurs varient : ne basez pas le contrôle du client sur leur texte.

Résultat attendu : le client corrige l’erreur permanente ou réessaie de façon bornée en conservant l’identifiant pour l’assistance.