Error codes — ePostman

Every SAPI error has the same shape and tells you whether retrying makes sense.

{
  "error": {
    "category": "VALIDATION",
    "code": "SAPI-VAL-003",
    "message": "payload is not well-formed XML",
    "correlation_id": "b1f0c2d4-7e19-4a3c-8f52-6d0e91ab7c33",
    "retryable": false,
    "timestamp": "2026-07-13T09:14:22.310Z"
  }
}

Code	HTTP	Retry	When it happens
`SAPI-AUTH-001`	401	no	Invalid credentials or token
`SAPI-AUTH-002`	403	no	The Peppol identifier is not yours
`SAPI-AUTH-003`	401	no	Missing or invalid `Authorization` header
`SAPI-AUTH-004`	403	no	The account is suspended or not yet approved
`SAPI-AUTH-005`	423	no	Account temporarily locked after repeated failures
`SAPI-VAL-001`	400	no	Malformed Peppol identifier
`SAPI-VAL-002`	400	no	A required header or the body is missing
`SAPI-VAL-003`	400	no	The `payload` is not well-formed XML
`SAPI-VAL-006`	400	no	`Idempotency-Key` is not a valid UUID
`SAPI-VAL-008`	400	no	Malformed `pageToken`
`SAPI-VAL-009`	409	no	Same idempotency key, different body
`SAPI-VAL-010`	413	no	The document exceeds 10 MB
`SAPI-VAL-020`	400	no	The page token expired (15 minutes)
`SAPI-PROC-003`	502	yes	A transient error on our side
`SAPI-PROC-004`	402	no	Not enough credit to send
`SAPI-PERM-002`	409	no	A document with the same number, supplier and type (invoice/credit note) is already in progress or was already dispatched
`SAPI-PERM-003`	404	no	The document does not exist
`SAPI-PERM-004`	410	no	The document’s retention period has lapsed
`SAPI-TEMP-001`	503	yes	The authentication service is temporarily down
`SAPI-TEMP-002`	429	yes	Rate limit exceeded — wait as told by `Retry-After`

Wrong method and unknown path

A wrong HTTP method returns 405 with an Allow header naming the right one — e.g. GET on /sapi/document/receive/{id}/acknowledge (the endpoint is POST) answers 405 with Allow: POST. The code in the envelope is SAPI-VAL-002.

An unknown path under /sapi/ returns 404 with code SAPI-PERM-003. Both use the same error envelope as the table above.