Erreurs

La forme

Chaque erreur renvoie le même JSON, sans trace de pile, SQL ni chemin de fichier :

{ "error": { "code": "authenticate_user.invalid_credentials", "message": "authenticate_user.invalid_credentials" } }

Le code est une clé de traduction stable, pas du texte localisé. Votre client la mappe vers un message dans la langue de l'utilisateur au rendu : le texte des erreurs vit donc chez vous et ne change jamais sous vos pieds.

Codes de statut

• 400 Bad Request : entrée malformée (email invalide, UUID incorrect, valeur de query inconnue, lot de moins de 20 adresses).
• 401 Unauthorized : clé ou jeton manquant ou invalide.
• 402 Payment Required : le portefeuille n'a pas de solde pour réserver le job. Distinct de 403 pour proposer une recharge plutôt qu'un correctif de permission.
• 403 Forbidden : la clé n'a pas la portée ou le contrôle requis.
• 404 Not Found : ressource inexistante pour votre compte (un UUID appartenant à autrui est indistinguable d'un UUID absent).
• 408 Request Timeout : la requête a dépassé le budget de traitement du serveur (request.timeout) ; réessayez sans risque.
• 409 Conflict : par exemple une clé d'idempotence réutilisée avec un corps différent.
• 429 Too Many Requests : limite de débit dépassée. La réponse porte Retry-After.

Pas d'énumération

Les échecs d'authentification renvoient la même erreur pour un email inconnu et un mauvais mot de passe : les réponses ne révèlent jamais si un compte existe.