REST API error handling — Poland
RFC 7807 problem+json errors, stable codes and retry guidance for the REST API in Poland.
Architecture — RFC 7807 problem+json for Poland
Every 4xx/5xx response uses Content-Type: application/problem+json with fields: type (stable URI), title, status, detail, instance (request id), plus extension fields per error type. The type URI is stable across versions and links to docs with retry/fix guidance. Always log instance — support can trace it end-to-end in under a minute.
How to wire it up — Catalogue of common errors
invalid_vat (VIES mismatch, retry after fix), invalid_sku (not in Poland catalog, fix), min_qty_violation (below MOQ, fix), invalid_tax_rate (mismatch with VAT 23%, fix), idempotency_conflict (same key, different body, fix), insufficient_inventory (escalate or wait), KSeF_unavailable (transient, retry with backoff). Full catalogue at /docs/errors with examples per code.
Operations and edge cases — 5xx errors and idempotency
5xx errors mean the request did not commit. We log the request id, alert on-call, and surface incidents on our status page. Idempotency keys protect you: retries with the same key after a 5xx never double-charge. Our SDKs retry 5xx with exponential backoff (max 3 attempts) by default — disable if your workflow requires manual control. Krajowy System e-Faktur (KSeF) failures are surfaced asynchronously via a webhook with retry hints.
FAQ
Is the error catalogue stable?
Yes — type URIs are versioned and we never repurpose a code. New codes are additive.
How do I correlate logs?
Every response has instance = a request id (cm-req-…). Pass to support and we can fetch the full trace in under a minute.
SDKs vs raw HTTP?
SDKs raise typed exceptions corresponding to the type URI — usually easier than parsing JSON. Raw HTTP works fine if you prefer.
What about validation errors?
422 with an errors array, one entry per offending field with a stable code and human message.
KSeF_unavailable?
Transient — our gateway buffers your invoice payload and retries to KSeF. We surface success via a webhook once accepted.