Obsługa błędów REST API — Polska
Błędy RFC 7807 problem+json, stabilne kody i wytyczne dla retry w REST API w Polska.
Architektura — RFC 7807 problem+json wszędzie w Polska
Każda odpowiedź 4xx/5xx ma Content-Type: application/problem+json z polami: type (stabilne URI), title, status, detail, instance (request id) oraz polami rozszerzającymi. type jest stabilne między wersjami i linkuje do dokumentacji z wskazówkami retry/fix. Zawsze loguj instance — support prześledzi je end-to-end w poniżej minuty.
Jak to zintegrować — Katalog typowych błędów
invalid_vat (niezgodność z VIES, retry po fixie), invalid_sku (poza katalogiem Polska, fix), min_qty_violation (poniżej MOQ, fix), invalid_tax_rate (niezgodność z VAT 23%, fix), idempotency_conflict (ten sam klucz, inne body, fix), insufficient_inventory (eskalacja lub czekanie), KSeF_unavailable (przejściowy, retry z backoffem). Pełny katalog na /docs/errors.
Eksploatacja i przypadki brzegowe — Błędy 5xx i idempotencja
Błędy 5xx oznaczają, że żądanie nie zostało zatwierdzone. Logujemy request id, alarmujemy on-call, publikujemy incydenty na status page. Klucze idempotency cię chronią: retry z tym samym kluczem po 5xx nigdy nie zaksięguje dwa razy. Nasze SDK retryują 5xx z wykładniczym backoffem (max 3 próby) — wyłączalne jeśli wolisz kontrolę ręczną. Awarie Krajowy System e-Faktur (KSeF) przekazywane asynchronicznie webhookiem z hintami retry.
FAQ
Czy katalog błędów jest stabilny?
Tak — type URI są wersjonowane i nigdy nie zmieniamy znaczenia kodu. Nowe są addytywne.
Jak korelować logi?
Każda odpowiedź ma instance = request id (cm-req-…). Przekaż supportowi, prześledzimy end-to-end w mniej niż minutę.
SDK czy raw HTTP?
SDK rzucają typowane wyjątki odpowiadające type URI — zwykle prościej niż parsowanie JSON. Raw HTTP też działa.
A walidacje?
422 z tablicą errors, jeden wpis na błędne pole ze stabilnym kodem i komunikatem.
KSeF_unavailable?
Przejściowe — nasz gateway buforuje payload faktury i retry do KSeF. Potwierdzenie webhookiem.