API Postilis · v1
Erreurs et limites
Une forme d’erreur unique, des messages en français prêts à afficher, et des limites claires.
Format des erreurs
Toute erreur a la même forme : un code stable, à tester dans votre programme, et un message en français, affichable tel quel à vos utilisateurs. Pour une erreur de validation, fields indique le message de chaque champ en cause.
Exemple
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
{
"error": {
"code": "validation",
"message": "Certains champs sont invalides.",
"fields": { "postal_code": "Le code postal doit comporter 5 chiffres." }
}
}
Codes d’erreur
400
bad_request
Requête mal formée : JSON invalide, partie multipart manquante, en-tête Idempotency-Key absent.
→ Corriger la requête.
401
unauthenticated
Clé absente, inconnue ou révoquée.
→ Vérifier l’en-tête Authorization ; créer une nouvelle clé si besoin.
402
insufficient_balance
Crédit insuffisant pour cet envoi (rien n’est débité).
→ Recharger le crédit, puis renvoyer la même requête (même Idempotency-Key).
403
api_access_denied
Le compte n’est pas (ou plus) un compte professionnel avec SIREN et e-mail confirmé.
→ Compléter le compte dans l’application.
403
forbidden
Opération réservée à votre compte Postilis (compte, clés, webhooks…), ou à une clé réelle (modification du carnet d’adresses, documents).
→ L’effectuer depuis l’application ou avec une clé réelle.
404
not_found
Élément introuvable, appartenant à un autre compte ou à l’autre mode (test / réel).
→ Vérifier l’identifiant et la clé utilisée.
409
invalid_state
Action impossible dans l’état actuel (brouillon déjà payé, document expiré…).
→ Relire l’élément (GET) avant d’agir.
409
postal_address_required
L’adresse postale du compte (expéditeur) n’est pas renseignée.
→ La renseigner dans l’application.
413
too_large
Fichier de plus de 100 Mo.
→ Réduire le PDF.
422
validation
Champs invalides : le détail figure dans fields (ex. postal_code).
→ Corriger les champs indiqués.
422
pdf_invalid
PDF illisible, protégé par mot de passe ou pages hors A4.
→ Enregistrer à nouveau le PDF au format A4, sans protection.
422
too_many_pages
Plus de 100 pages.
→ Scinder le document.
422
quota_exceeded
Plus de 1 Go de documents sur 24 heures glissantes.
→ Réessayer plus tard.
422
idempotency_key_reused
Cette Idempotency-Key a déjà servi pour un autre envoi.
→ Utiliser une clé unique par courrier.
429
rate_limited
Trop de requêtes.
→ Patienter (en-tête Retry-After) puis réessayer.
500
internal
Erreur inattendue (notre équipe est alertée).
→ Réessayer avec la même Idempotency-Key : aucun double envoi possible.
503
orders_closed
Nouveaux envois momentanément suspendus (message fourni).
→ Réessayer plus tard ; les envois en cours ne sont pas concernés.
Limites
Requêtes
par adresse IP
300 par minute, toutes routes confondues.
POST /letters
par compte
60 envois par minute.
Recharges
par compte
10 par minute ; 10 € à 2 000 € par recharge ; crédit de 5 000 € au plus.
Fichier PDF
par envoi
A4, 100 pages, 100 Mo, sans mot de passe.
Documents
par compte
1 Go sur 24 heures glissantes.
Clés d’API
par compte
20 clés actives.
Webhooks
par compte
10 adresses ; réponse attendue en 10 secondes.
Au-delà, l’API répond 429 rate_limited avec l’en-tête Retry-After (en secondes) : patientez avant de réessayer. Pour un grand nombre de courriers, étalez les envois (par exemple une file d’attente traitée à quelques envois par seconde).
Reprendre après une erreur
- •4xx : la requête doit être corrigée (sauf 429, à réessayer plus tard). La renvoyer à l’identique produira la même erreur.
- •5xx, coupure réseau, délai dépassé : l’issue est incertaine. Renvoyez la même requête avec la même `Idempotency-Key` : vous obtiendrez l’envoi s’il a été créé, sans jamais de second courrier.
- •Espacez les nouvelles tentatives (par exemple 1 s, 5 s, 30 s, 2 min).
Versions de l’API
L’API est versionnée dans son adresse (/api/v1). Au sein d’une version, nous ajoutons des champs et des routes sans rien retirer : ignorez les champs que vous ne connaissez pas.