HTTP-Statuscodes, Fehlerantworten und Retry-Logik der PSB API: So bauen Sie eine robuste Integration.
Jede API-Integration wird früher oder später auf Fehler stoßen. Ein Netzwerkausfall, ein nicht erreichbarer Server, ein falsch formatiertes Dokument: Das gehört dazu. Die PSB API kommuniziert Fehler über standardmäßige HTTP-Statuscodes und strukturierte JSON-Antworten. Darüber hinaus verfügt die PSB über einen integrierten Retry-Mechanismus, der temporäre Fehler bei der Dokumentzustellung automatisch behandelt.
In diesem Artikel erfahren Sie, welche Statuscodes die PSB zurückgibt, wie Sie Fehlerantworten interpretieren, wann ein Retry sinnvoll ist und wie der automatische Retry-Mechanismus der PSB funktioniert.
Die PSB API verwendet standardmäßige HTTP-Statuscodes, um das Ergebnis einer Anfrage anzuzeigen. Die Statuscodes fallen in zwei Kategorien: Client-Fehler (4xx), die Sie selbst beheben müssen, und Serverfehler (5xx), bei denen ein Retry möglich ist.
Bei einem 4xx-Fehler liegt das Problem in der Anfrage selbst. Erneutes Senden mit denselben Daten führt zum gleichen Ergebnis. Beheben Sie die Ursache, bevor Sie es erneut versuchen.
VerstuurInvoice): Die angebotene PartyId steht (für diesen Dokumenttyp) nicht auf Peppol/SMPqueryRecipientParty oder lookup.peppol.org für die angebotene ID durch, prüfen Sie danach optional verwandte Schemes (zum Beispiel BE 0208 versus 9925/BE:VAT, gleiche Kernnummer) -- nur bei einem bestätigten Lookup-Treffer eine EndpointID-Änderung empfehlen. Kein Treffer bei irgendeiner Kandidaten-ID: Der Empfänger ist unter diesen Identifiers nicht erreichbar; der Kunde muss beim Empfänger eine Registrierung oder eine andere Liefer-ID erfragenapplication/json, wo erforderlichqueryRecipientParty-Aufruf. Fehlermeldung: EConnect.Psb.Models.EConnectException: 'Duplicate id agencies {code} requested.' (wobei {code} der Agentur-Code ohne führende Null ist, z.B. Schema 0208 → 208).API403 Access forbidden: Die wörtliche Fehlermeldung [API403] Access forbidden. Please check PartyId authorization and make sure the Subscription-Key is valid kann unter anderem bei einer fehlgeschlagenen Peppol-Übermittlung aus Business Central ("delivery failed") auftreten, die Ursache ist jedoch generisch für die PSB und nicht BC-spezifisch. Diagnosereihenfolge:
Hinweis: Die Erwähnung von "Subscription-Key" in der Fehlermeldung bedeutet nicht automatisch, dass der Key erneuert werden muss. PartyId-Autorisierung und ein plattformseitiges Verknüpfungsproblem sind ebenso häufige Ursachen. Schlägt die Zustellung nach einer gültigen Token- und PartyId-Prüfung weiterhin fehl, eskalieren Sie an den eConnect-Support, statt wiederholt den Subscription-Key zu rotieren.
SBDH-Envelope-Validierung (API400.USRMS1 / API400.USRMS2): Diese Fehlercodes weisen auf eine Diskrepanz zwischen dem Peppol-Envelope (SBDH) und dem E-Rechnungsdokument selbst hin. Bei USRMS1 stimmt der Absender oder Empfänger im Envelope nicht mit den Identifikatoren in der Rechnungs-XML überein. Bei USRMS2 kann die PSB keinen erkennbaren Absender im Dokument finden. Stellen Sie sicher, dass EndpointID und PartyIdentification in Ihrem UBL mit den beim Senden angegebenen Werten übereinstimmen. Die PSB lehnt das Dokument auf AS4-Ebene ab und gibt den Fehler an den sendenden Access Point zurück.
Eine Ausnahme von der Regel „nur 5xx ist retry-fähig“: 429 Too Many Requests weist auf Rate Limiting hin und ist retry-fähig. Warten Sie und beachten Sie den Retry-After-Header, bevor Sie die Anfrage erneut senden.
Retry-After-Header beachten, danach erneut versuchenEin 5xx-Fehler weist auf ein vorübergehendes Problem auf der Serverseite hin. Die Anfrage selbst kann korrekt sein. Zusammen mit 429 sind dies die einzigen Statuscodes, bei denen ein Retry sinnvoll ist.
Hinweis: Der Send-Endpunkt akzeptiert maximal 24 MB pro Anfrage, einschließlich HTTP-Overhead. Payloads, die dieses Limit überschreiten, werden vom Webserver mit einem HTTP 500 statt einem 413 abgelehnt, da die Ablehnung erfolgt, bevor die Anwendungsschicht ihre Validierung durchführt. Beachten Sie dies bei Base64-kodierten Anhängen: Diese erhöhen die Dateigröße um etwa 33%.
API500UH bei Deployments: Der Fehlercode API500UH (Unhandled Error) kann auftreten, wenn die PSB ein internes Service-Update durchführt (Service-Fabric-Deployment). In vielen Fällen wurde das Dokument bereits erfolgreich an den Empfänger zugestellt, aber der Bestätigungsschritt schlägt aufgrund der Migration fehl. Der Retry-Mechanismus der PSB versucht automatisch, die verbleibenden Schritte abzuschließen. Wenn Sie einen API500UH erhalten, prüfen Sie über die Statusereignisse, ob das Dokument zugestellt wurde, bevor Sie es erneut senden.
Bei einem 4xx-Fehler enthält die Antwort einen JSON-Body, der das Problem beschreibt. Diese Informationen helfen Ihnen, die Ursache schnell zu identifizieren.
{
"error": "Validation failed",
"message": "The supplied document is not valid UBL 2.1",
"details": [
"cbc:InvoiceTypeCode is missing"
]
}
Bei einem 5xx-Fehler ist die Antwort nicht immer strukturiert. Basieren Sie Ihre Retry-Logik auf dem HTTP-Statuscode, nicht auf dem Inhalt des Bodys.
Nicht jeder Fehler verdient einen Retry. Die Faustregel ist einfach: Nur 5xx-Statuscodes und Netzwerk-Timeouts sind einen Retry wert. Bei 4xx-Fehlern müssen Sie die Anfrage ändern, bevor Sie sie erneut senden.
Die empfohlene Retry-Strategie ist Exponential Backoff: Beginnen Sie mit einer kurzen Wartezeit und verdoppeln Sie diese mit jedem weiteren Versuch.
Tipp: Fügen Sie eine kleine zufällige Streuung (Jitter) zur Wartezeit hinzu. Wenn nach einem Ausfall mehrere Clients gleichzeitig einen Retry durchführen, verhindert Jitter, dass alle den Server im selben Moment treffen.
Kombinieren Sie Ihre Retry-Logik immer mit dem X-EConnect-DocumentId-Header. Indem Sie bei jedem Versuch dieselbe documentId mitsenden, garantiert die PSB, dass ein Dokument niemals doppelt verarbeitet wird. Wenn die PSB eine documentId erhält, die bereits verarbeitet wurde, gibt sie zur Bestätigung einen 409 Conflict zurück.
Siehe Idempotenz: doppelte Einreichungen verhindern für die vollständige Erklärung und Codebeispiele.
Neben der Retry-Logik, die Sie selbst implementieren, verfügt die PSB über einen eigenen Retry-Mechanismus für die Dokumentzustellung. Wenn die PSB versucht, eine Rechnung oder Bestellung an den Empfänger zuzustellen und dieser einen 5xx-Fehler zurückgibt, nimmt die PSB die Zustellung automatisch wieder auf.
Die PSB unternimmt bis zu 8 Retry-Versuche, verteilt über etwa 35 Stunden. Bei jedem Versuch veröffentlicht die PSB ein Ereignis, damit Sie den Fortschritt verfolgen können:
InvoiceSentRetryInvoiceSentErrorOrderSentRetryOrderSentErrorWenn Sie einen Webhook für diese Topics konfiguriert haben, erhalten Sie bei jedem Versuch eine Benachrichtigung. Nach einem InvoiceSentError oder OrderSentError ist manuelles Eingreifen erforderlich: Kontaktieren Sie den Empfänger oder eskalieren Sie über den eConnect Support.
Tipp: Abonnieren Sie die Topics
InvoiceSentRetryundInvoiceSentErrorüber einen Webhook. So erkennen Sie Zustellprobleme sofort und können proaktiv handeln.
Für Webhooks verwendet die PSB einen separaten Retry-Zeitplan. Wenn Ihr Webhook-Endpunkt nicht erreichbar ist oder keinen 2xx-Statuscode zurückgibt, versucht die PSB erneut, das Ereignis zuzustellen.
HookSentRetryHookSentErrorDie PSB erwartet innerhalb von 100 Sekunden eine 2xx-Antwort von Ihrem Endpunkt. Jede andere Antwort (oder ein Timeout) gilt als fehlgeschlagener Versuch. Verarbeiten Sie eingehende Webhooks daher so schnell wie möglich, bestätigen Sie den Empfang mit einem 200 OK und führen Sie aufwendige Verarbeitung asynchron in einem Hintergrundprozess durch.
Hinweis: Wenn Ihr Endpunkt über einen längeren Zeitraum nicht erreichbar ist, stellt die PSB die Retries nach 5 Tagen ein. Verpasste Ereignisse können weiterhin über den Batch-Endpunkt abgerufen werden. Siehe Batch-Hooks für weitere Informationen.
Bei Integrationen, die auf die PSB aus einem abgeschirmten Netzwerk (Firewall, Proxy, Allowlist) zugreifen, müssen sowohl die primären als auch die Failover-Hostnamen zugelassen werden. everbinding.nl ist die Legacy-Domain von eConnect und wird aktiv für PSB-Failover verwendet.
psb.econnect.euapi.everbinding.nlaccp-psb.econnect.eutestapi.everbinding.nlWhitelisten Sie alle vier Hostnamen auf Port 443 (HTTPS). Ohne die Failover-Hostnamen kann eine gültige PSB-Verbindung während eines Fail-Events unerreichbar werden, während die PSB selbst noch läuft.
Retry-After warten, Exponential BackoffZusammenfassung
Client-Fehler (4xx) erfordern Ihre Aufmerksamkeit: Beheben Sie das Problem in Ihrer Anfrage. Serverfehler (5xx) sind vorübergehend und können sicher mit Exponential Backoff erneut versucht werden. Verwenden Sie immer den X-EConnect-DocumentId-Header, um doppelte Verarbeitung bei Retries zu verhindern. Die PSB wiederholt die Dokumentzustellung automatisch bis zu 8 Mal über etwa 35 Stunden und Webhooks bis zu 5 Tage lang.
Vollständige API-Dokumentation ansehen