# Error codes

URL: https://postman.slovakodata.com/developers/en/chyby/
Updated: 2026-07-24

The SAPI error response shape and the full list of codes with HTTP status and retryability.

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

```json
{
  "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"
  }
}
```

**Trust the `retryable` field.** Do not infer retry behaviour from the HTTP
status. When `retryable: false`, retrying will never help — fix the request
instead. When `true`, retry with exponential backoff.

When reporting a problem, send us the `correlation_id`, the time of the request
and the path it went to. The `correlation_id` itself is not written to our logs —
it is created with the response — so we locate the request by time and path.

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