Every API integration will encounter errors sooner or later. A network outage, an unreachable server, an incorrectly formatted document: it comes with the territory. The PSB API communicates errors through standard HTTP status codes and structured JSON responses. In addition, the PSB has a built-in retry mechanism that automatically handles temporary errors during document delivery.

In this article you will learn which status codes the PSB returns, how to interpret error responses, when you can safely retry and how the PSB's automatic retry mechanism works.

The PSB API uses standard HTTP status codes to indicate the result of a request. The status codes fall into two categories: client errors (4xx) that you need to fix yourself, and server errors (5xx) that you can retry.

With a 4xx error the problem is in the request itself. Resending with the same data will produce the same result. Fix the cause before trying again.

A 5xx error indicates a temporary problem on the server side. The request itself may be correct. These are the only status codes where retrying makes sense.

Note: the send endpoint accepts a maximum of 24 MB per request, including HTTP overhead. Payloads exceeding this limit are rejected by the web server with an HTTP 500 instead of a 413, because the rejection occurs before the application layer performs its validation. Keep this in mind with base64-encoded attachments: they add approximately 33% to the file size.

With a 4xx error the response contains a JSON body describing the problem. This information helps you identify the cause quickly.

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

With a 5xx error the response is not always structured. Base your retry logic on the HTTP status code, not on the content of the body.

Not every error deserves a retry. The rule of thumb is simple: only 5xx status codes and network timeouts are worth retrying. With 4xx errors you need to modify the request before sending it again.

The recommended retry strategy is exponential backoff: start with a short wait time and double it with each subsequent attempt.

Tip: add a small random spread (jitter) to the wait time. If multiple clients retry simultaneously after an outage, jitter prevents them from all hitting the server at the same moment.

Always combine your retry logic with the X-EConnect-DocumentId header. By including the same documentId with each attempt, the PSB guarantees that a document is never processed twice. If the PSB receives a documentId that has already been processed, it returns a 409 Conflict as confirmation.

See Idempotency: preventing duplicate submissions for the full explanation and code examples.

In addition to the retry logic you implement yourself, the PSB has its own retry mechanism for document delivery. If the PSB attempts to deliver an invoice or order to the recipient and that party returns a 5xx error, the PSB automatically resumes delivery.

The PSB makes up to 8 retry attempts spread over approximately 35 hours. With each attempt the PSB publishes an event so you can track progress:

If you have configured a webhook for these topics, you receive a notification with each attempt. After an InvoiceSentError or OrderSentError, manual action is required: contact the recipient or escalate via eConnect Support.

Tip: subscribe to the InvoiceSentRetry and InvoiceSentError topics via a webhook. This way you detect delivery issues immediately and can act proactively.

For webhooks the PSB uses a separate retry schedule. If your webhook endpoint is unreachable or does not return a 2xx status code, the PSB retries delivering the event.

The PSB expects a 2xx response from your endpoint within 100 seconds. Any other response (or a timeout) counts as a failed attempt. Therefore, process incoming webhooks as quickly as possible, confirm receipt with a 200 OK and perform heavy processing asynchronously in a background process.

Note: if your endpoint is unreachable for an extended period, the PSB stops retrying after 5 days. Missed events can still be retrieved via the batch endpoint. See Batch hooks for more information.