Elke API-integratie krijgt vroeg of laat te maken met fouten. Een netwerkstoring, een onbereikbare server, een verkeerd geformateerd document: het hoort erbij. De PSB API communiceert fouten via standaard HTTP-statuscodes en gestructureerde JSON-responses. Daarnaast heeft de PSB een ingebouwd retry-mechanisme dat tijdelijke fouten bij documentaflevering automatisch afvangt.

In dit artikel leer je welke statuscodes de PSB retourneert, hoe je foutresponses interpreteert, wanneer je veilig kunt retrien en hoe het automatische retry-mechanisme van de PSB werkt.

De PSB API gebruikt standaard HTTP-statuscodes om het resultaat van een verzoek aan te geven. De statuscodes vallen in twee categorieën: client-fouten (4xx) die je zelf moet oplossen, en server-fouten (5xx) die je kunt retrien.

Bij een 4xx-fout zit het probleem in het verzoek zelf. Opnieuw versturen met dezelfde data levert hetzelfde resultaat op. Los eerst de oorzaak op voordat je het opnieuw probeert.

Een 5xx-fout duidt op een tijdelijk probleem aan de serverkant. Het verzoek zelf is mogelijk correct. Dit zijn de enige statuscodes waarbij retrien zinvol is.

Let op: het send-endpoint accepteert maximaal 24 MB per request, inclusief HTTP-overhead. Payloads die deze grens overschrijden worden door de webserver afgewezen met een HTTP 500 in plaats van een 413, omdat de afwijzing plaatsvindt vóórdat de applicatielaag de validatie uitvoert. Houd hier rekening mee bij base64-encoded bijlagen: die voegen circa 33% toe aan de bestandsgrootte.

Bij een 4xx-fout bevat de response een JSON-body met een beschrijving van het probleem. Deze informatie helpt je om de oorzaak snel te achterhalen.

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

Bij een 5xx-fout is de response niet altijd gestructureerd. Baseer je retry-logica daarom op de HTTP-statuscode, niet op de inhoud van de body.

Niet elke fout verdient een retry. De vuistregel is eenvoudig: alleen 5xx-statuscodes en netwerk-timeouts zijn het opnieuw proberen waard. Bij 4xx-fouten moet je het verzoek aanpassen voordat je het opnieuw stuurt.

De aanbevolen retry-strategie is exponential backoff: begin met een korte wachttijd en verdubbel die bij elke volgende poging.

Tip: voeg een kleine willekeurige spreiding (jitter) toe aan de wachttijd. Als meerdere clients tegelijkertijd retrien na een storing, voorkomt jitter dat ze allemaal op hetzelfde moment de server belasten.

Combineer je retry-logica altijd met de X-EConnect-DocumentId-header. Door bij elke poging hetzelfde documentId mee te sturen, garandeert de PSB dat een document nooit dubbel wordt verwerkt. Ontvangt de PSB een documentId dat al verwerkt is, dan retourneert hij een 409 Conflict als bevestiging.

Zie Idempotency: dubbele verzendingen voorkomen voor de volledige uitleg en codevoorbeelden.

Naast de retry-logica die je zelf implementeert, heeft de PSB een eigen retry-mechanisme voor documentaflevering. Als de PSB een factuur of order probeert af te leveren bij de ontvanger en die partij retourneert een 5xx-fout, dan hervat de PSB de aflevering automatisch.

De PSB doet maximaal 8 herpogingen verspreid over circa 35 uur. Bij elke poging publiceert de PSB een event zodat je de voortgang kunt volgen:

Als je een webhook hebt geconfigureerd voor deze topics, ontvang je bij elke poging een notificatie. Na een InvoiceSentError of OrderSentError is handmatige actie nodig: neem contact op met de ontvanger of escaleer via eConnect Support.

Tip: abonneer je op de InvoiceSentRetry- en InvoiceSentError-topics via een webhook. Zo detecteer je afleveringsproblemen direct en kun je proactief handelen.

Voor webhooks hanteert de PSB een apart retry-schema. Als jouw webhook-endpoint niet bereikbaar is of geen 2xx-statuscode retourneert, probeert de PSB het event opnieuw te bezorgen.

De PSB verwacht binnen 100 seconden een 2xx-response van je endpoint. Elke andere response (of een timeout) telt als mislukte poging. Verwerk daarom inkomende webhooks zo snel mogelijk, bevestig de ontvangst met een 200 OK en doe zware verwerking asynchroon in een achtergrondproces.

Let op: als je endpoint langdurig onbereikbaar is, stopt de PSB na 5 dagen met herpogingen. Gemiste events kun je alsnog ophalen via het batch-endpoint. Zie Batch hooks voor meer informatie.