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.
400	`bad_request`	Corps illisible (JSON mal formé) ou en-tête invalide (Idempotency-Key de plus de 255 caractères…). Corrigez la requête.
400	`invalid_cursor`	Curseur de pagination illisible : reprenez la liste sans cursor.
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).
403	`insufficient_scope`	La clé n’a pas le droit de cette route (details.required, details.granted) : utilisez ou créez une clé avec ce droit.
404	`not_found`	Lettre, fournisseur, envoi, établissement ou itinéraire introuvable ; details.reason précise le cas quand il y en a un (route_not_found : aucun itinéraire entre les deux adresses).
409	`conflict`	Opération impossible dans l’état actuel (envoi déjà à sa dernière étape…).
409	`idempotency_in_progress`	Une requête avec la même Idempotency-Key est encore en cours : réessayez après Retry-After (1 s).
422	`address_invalid`	Adresse postale incomplète ; details.missing liste les adresses à corriger.
413	`payload_too_large`	Corps de plus de 1 Mo : allégez la requête (signature PNG comprise).
422	`letter_incomplete`	Lettre du catalogue : champs obligatoires manquants (details.missing). Complétez values.
422	`recipient_email_required`	Recommandé électronique (mode lre) : l’e-mail du destinataire est obligatoire.
422	`mode_unavailable`	Mode d’envoi indisponible chez le prestataire postal actuel : choisissez un autre mode.
422	`address_not_found`	Devis ou calculateur : adresse introuvable (details.field) ; utilisez /v1/geo/addresses.
422	`commune_required`	Devis : la commune est obligatoire (champ commune, valeur label de /v1/geo/cities).
422	`commune_not_found`	Devis : commune introuvable (details.field) ; utilisez /v1/geo/cities.
422	`expense_invalid`	Partage de dépenses : un index de participant dépasse la liste people (details.expense).
422	`idempotency_key_reused`	Cette Idempotency-Key a déjà servi pour une autre requête : une clé neuve par opération.
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.
503	`prices_unavailable`	Grille tarifaire momentanément illisible : aucun appel payant n’est exécuté ni débité ; réessayez.
503	`ai_unavailable`	Outil IA momentanément indisponible (coupe-circuit) : rien n’est débité ; réessayez plus tard.
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, délai dépassé ou connexion coupée : réessayez avec un délai croissant (1 s, 5 s, 30 s…), avec la même Idempotency-Key. Vous ne savez pas si la première requête a abouti ; la clé garantit qu’elle ne s’exécute qu’une fois (voir idempotence).
Une erreur n’est pas facturée, sauf un appel IA auquel le modèle a répondu (sortie tronquée, refusée ou inexploitable) : son débit est conservé et details.charged vaut true. Au-delà de 50 appels IA en échec dans la journée, l’IA de votre compte répond 429 ai_failure_limit jusqu’à minuit. Un envoi en 502 a été refusé par le prestataire : il est marqué en erreur, recrédité, et son identifiant figure dans details.mailingId.

Étape suivante : les limites de débit