Erreurs

Toute erreur renvoie un statut HTTP 4xx ou 5xx et le même corps JSON : un code stable (à tester dans votre code), un message en français (à afficher ou journaliser) et parfois des details.

Corps d’une erreur

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "(facultatif)"
  }
}

Exemple : adresse postale incomplète

Réponse 422

{
  "error": {
    "code": "address_invalid",
    "message": "Pour un envoi postal, les adresses doivent comporter un nom, une rue (ou une boîte postale : BP, TSA, CS), un code postal à 5 chiffres et une ville.",
    "details": {
      "missing": [
        {
          "key": "sender",
          "label": "Adresse de l’expéditeur (nom, rue, code postal et ville)"
        },
        {
          "key": "recipient",
          "label": "Adresse du destinataire (nom, rue ou boîte postale, code postal et ville)"
        }
      ]
    }
  }
}

Codes

HTTP	Code	Signification
400	`validation_error`	Corps ou paramètres invalides ; details.issues liste les champs fautifs. Corrigez la requête.
401	`invalid_api_key`	Clé absente, mal formée ou inconnue.
401	`revoked_api_key`	Clé révoquée : utilisez une clé active.
402	`insufficient_balance`	Crédit insuffisant pour cet appel payant : rien n’a été exécuté ni débité. details donne balanceCents et priceCents. Rechargez depuis l’espace développeur.
403	`live_not_enabled`	Clé live alors que la production n’est pas ouverte.
403	`account_suspended`	Compte suspendu : écrivez-nous.
403	`test_only`	Route réservée au bac à sable (clé test).
404	`not_found`	Lettre, fournisseur, envoi ou établissement introuvable.
409	`conflict`	Opération impossible dans l’état actuel (envoi déjà à sa dernière étape…).
422	`address_invalid`	Adresse postale incomplète ; details.missing liste les adresses à corriger.
422	`inputs_incomplete`	Outil IA : champs obligatoires manquants (details.missing).
422	`inputs_too_long`	Outil IA : texte trop long (details.max).
422	`inputs_invalid`	Outil IA : un lien seul ou un texte trop court a été envoyé à la place du texte à traiter (details.invalid).
429	`rate_limited`	Trop d’appels : attendez Retry-After secondes.
429	`test_quota_exceeded`	Quota quotidien du bac à sable atteint.
502	`upstream_error`	Un prestataire (La Poste, annuaire, IA) n’a pas répondu. Pour un envoi, rien n’est facturé ; réessayez.
503	`unavailable`	Service momentanément indisponible ; réessayez.
500	`internal_error`	Erreur inattendue, nos équipes sont prévenues ; réessayez.

Réessayer sans risque

4xx : ne réessayez pas à l’identique, corrigez d’abord (sauf 429 : attendez Retry-After).
502, 503, 500 : réessayez avec un délai croissant (1 s, 5 s, 30 s…).
Une erreur n’est jamais facturée. Pour un envoi en 502, le détail porte mailingId : l’envoi est marqué en erreur, créez-en un nouveau.

Étape suivante : les limites de débit