Toute intégration API rencontrera tôt ou tard des erreurs. Une panne réseau, un serveur inaccessible, un document mal formaté : cela fait partie du métier. L'API PSB communique les erreurs via des codes de statut HTTP standard et des réponses JSON structurées. De plus, la PSB dispose d'un mécanisme de réessai intégré qui gère automatiquement les erreurs temporaires lors de la livraison de documents.

Dans cet article, vous apprendrez quels codes de statut la PSB renvoie, comment interpréter les réponses d'erreur, quand un réessai est pertinent et comment fonctionne le mécanisme de réessai automatique de la PSB.

L'API PSB utilise des codes de statut HTTP standard pour indiquer le résultat d'une requête. Les codes de statut se divisent en deux catégories : les erreurs client (4xx) que vous devez corriger vous-même, et les erreurs serveur (5xx) que vous pouvez réessayer.

Avec une erreur 4xx, le problème se trouve dans la requête elle-même. Renvoyer avec les mêmes données produira le même résultat. Corrigez la cause avant de réessayer.

Une exception à la règle « seul le 5xx est réessayable » : 429 Too Many Requests indique une limitation de débit et est réessayable. Attendez et respectez l'en-tête Retry-After avant de renvoyer la requête.

Une erreur 5xx indique un problème temporaire côté serveur. La requête elle-même peut être correcte. Avec le 429, ce sont les seuls codes de statut pour lesquels un réessai a du sens.

Remarque : le endpoint d'envoi accepte un maximum de 24 Mo par requête, overhead HTTP inclus. Les payloads dépassant cette limite sont rejetés par le serveur web avec un HTTP 500 au lieu d'un 413, car le rejet intervient avant que la couche applicative n'effectue sa validation. Gardez cela à l'esprit avec les pièces jointes encodées en Base64 : elles ajoutent environ 33% à la taille du fichier.

Avec une erreur 4xx, la réponse contient un corps JSON décrivant le problème. Ces informations vous aident à identifier rapidement la cause.

{
  "error": "Validation failed",
  "message": "The supplied document is not valid UBL 2.1",
  "details": [
    "cbc:InvoiceTypeCode is missing"
  ]
}

Avec une erreur 5xx, la réponse n'est pas toujours structurée. Basez votre logique de réessai sur le code de statut HTTP, pas sur le contenu du corps.

Toutes les erreurs ne méritent pas un réessai. La règle de base est simple : seuls les codes de statut 5xx et les timeouts réseau valent un réessai. Avec les erreurs 4xx, vous devez modifier la requête avant de la renvoyer.

La stratégie de réessai recommandée est l'exponential backoff : commencez avec un temps d'attente court et doublez-le à chaque tentative suivante.

Conseil : ajoutez une petite variation aléatoire (jitter) au temps d'attente. Si après une panne plusieurs clients réessaient simultanément, le jitter empêche qu'ils frappent tous le serveur au même moment.

Combinez toujours votre logique de réessai avec le header X-EConnect-DocumentId. En incluant le même documentId à chaque tentative, la PSB garantit qu'un document n'est jamais traité deux fois. Si la PSB reçoit un documentId qui a déjà été traité, elle renvoie un 409 Conflict en guise de confirmation.

Voir Idempotence : éviter les soumissions en double pour l'explication complète et les exemples de code.

En plus de la logique de réessai que vous implémentez vous-même, la PSB dispose de son propre mécanisme de réessai pour la livraison de documents. Si la PSB tente de livrer une facture ou une commande au destinataire et que celui-ci renvoie une erreur 5xx, la PSB reprend automatiquement la livraison.

La PSB effectue jusqu'à 8 tentatives de réessai réparties sur environ 35 heures. À chaque tentative, la PSB publie un événement pour que vous puissiez suivre la progression :

Si vous avez configuré un webhook pour ces topics, vous recevez une notification à chaque tentative. Après un InvoiceSentError ou OrderSentError, une action manuelle est nécessaire : contactez le destinataire ou escaladez via le support eConnect.

Conseil : abonnez-vous aux topics InvoiceSentRetry et InvoiceSentError via un webhook. Vous détecterez ainsi immédiatement les problèmes de livraison et pourrez agir de manière proactive.

Pour les webhooks, la PSB utilise un calendrier de réessai distinct. Si votre endpoint webhook est inaccessible ou ne renvoie pas un code de statut 2xx, la PSB réessaie de livrer l'événement.

La PSB attend une réponse 2xx de votre endpoint dans les 100 secondes. Toute autre réponse (ou un timeout) compte comme une tentative échouée. Traitez donc les webhooks entrants le plus rapidement possible, confirmez la réception avec un 200 OK et effectuez les traitements lourds de manière asynchrone dans un processus en arrière-plan.

Remarque : si votre endpoint est inaccessible pendant une période prolongée, la PSB arrête les réessais après 5 jours. Les événements manqués peuvent toujours être récupérés via le endpoint batch. Voir Batch hooks pour plus d'informations.

Pour les intégrations qui accèdent à la PSB depuis un réseau protégé (pare-feu, proxy, liste d'autorisation), les noms d'hôtes principaux et de basculement doivent être autorisés. everbinding.nl est l'ancien domaine eConnect et est activement utilisé pour le basculement PSB.

Mettez les quatre noms d'hôtes sur liste blanche sur le port 443 (HTTPS). Sans les noms d'hôtes de basculement, une connexion PSB valide peut devenir inaccessible lors d'un événement de basculement, tandis que la PSB elle-même fonctionne toujours.

• Idempotence : éviter les soumissions en double
• Authentification : accéder à l'API PSB
• Configurer et sécuriser les webhooks
• Premiers pas avec l'API PSB
• Aperçu de la PSB : architecture et fonctionnalités
• Qu'est-ce que Peppol et comment fonctionne le réseau ?