Przewodniki

Błędy i kody błędów

Każdy błąd ma stały kod do obsługi w programie, czytelny opis i link do tej strony. Błędy KSeF dostają własny kod API i oryginalny numer KSeF.

Format błędu

Każdy błąd to kod HTTP i JSON z obiektem error. W programie opieraj się na code: jest stały. message jest dla ludzi i może się zmieniać.

{
  "error": {
    "type": "invalid_request_error",
    "code": "buyer_nip_invalid",
    "message": "buyer.nip is not a valid Polish NIP (checksum).",
    "param": "order.buyer.nip",
    "doc_url": "https://ksefshop.pl/api/errors#buyer_nip_invalid"
  }
}

typestringwymagane
Rodzaj błędu.
Jedna z: invalid_request_error, authentication_error, permission_error, not_found_error, idempotency_error, rate_limit_error, invoice_error, ksef_error, api_error
codestringwymagane
Stały kod do obsługi w programie. Lista kodów
Jedna z: parameter_missing, parameter_invalid, body_invalid_json, body_too_large, buyer_nip_missing, buyer_nip_invalid, order_not_paid, order_cancelled, currency_not_supported, vat_rate_missing, vat_rate_unsupported, order_unprocessable, correction_requires_invoice, livemode_mismatch, resource_missing, route_not_found, method_not_allowed, pdf_not_ready, api_key_missing, api_key_invalid, live_mode_disabled, idempotency_key_reused, idempotency_key_invalid, rate_limited, internal_error, seller_not_configured, plan_limit_reached, invoice_build_failed, invoice_schema_invalid, original_not_invoiced, original_rejected, ksef_not_connected, ksef_auth_failed, ksef_duplicate_number, ksef_rejected, ksef_unavailable
messagestringwymagane
Opis dla człowieka (po angielsku); może się zmieniać.
paramstring
Ścieżka JSON parametru, np. order.buyer.nip.
ksef_codeinteger
Własny kod liczbowy KSeF (np. 440 duplikat, 450 faktura niepoprawna).
doc_urlstringwymagane
Link do opisu kodu na tej stronie.

Błędy żądania i błędy dokumentu

Błędy żądania wracają od razu z kodem HTTP 4xx lub 5xx i niczego nie zapisują. Błędy dokumentu pojawiają się później, gdy API już przyjęło zamówienie: kolejka nie mogła zbudować faktury albo KSeF ją odrzucił. Wtedy faktura ma status rejected, skipped lub error, błąd jest w polu last_error (z type równym invoice_error albo ksef_error), a webhook wysyła invoice.rejected lub invoice.skipped.

`type`	Kiedy
`invalid_request_error`	Błędne dane żądania (400, 405, 409, 413, 422)
`authentication_error`	Brak lub zły klucz (401)
`permission_error`	Brak uprawnień, np. tryb produkcyjny wyłączony (403)
`not_found_error`	Nie ma obiektu lub endpointu (404)
`idempotency_error`	Problem z `Idempotency-Key` (400, 409)
`rate_limit_error`	Przekroczony limit (429)
`api_error`	Błąd po naszej stronie (500)
`invoice_error`	Dokumentu nie da się zbudować (w `last_error`)
`ksef_error`	Problem z KSeF (w `last_error`)

Odpowiedzi KSeF i kody API

KSeF ma własne kody liczbowe. Zamieniamy je na kody API, a oryginalny numer zostawiamy w ksef_code, żeby dało się go sprawdzić w dokumentacji KSeF.

Co odpowiedział KSeF	Kod w API	Co dzieje się dalej
Kod 440: numer faktury już użyty przez inną fakturę tego sprzedawcy	`ksef_duplicate_number`	Status `rejected`, `ksef_code: 440`. Sprawdź, czy ten sam numer nie poszedł z innego programu.
Inny kod odrzucenia, np. 450 (faktura niepoprawna)	`ksef_rejected`	Status `rejected`, kod i treść KSeF w `ksef_code` i `message`.
Brak odpowiedzi, przekroczony czas lub kod bez odrzucenia	`ksef_unavailable`	Status zostaje w kolejce, wysyłka ponawia się sama.
Certyfikat lub token odrzucony (wygasł, unieważniony, brak uprawnień do NIP)	`ksef_auth_failed`	Wgraj nowy certyfikat lub token w panelu; faktury czekają.
Brak certyfikatu i tokenu dla tego trybu	`ksef_not_connected`	Połącz KSeF w panelu dla trybu testowego albo produkcyjnego.
XML FA(3) nie przechodzi schematu XSD (sprawdzamy przed wysłaniem)	`invoice_schema_invalid`	Do KSeF nic nie poszło. Napisz do nas z `Request-Id` lub id faktury.

Wszystkie kody błędów

Każdy kod ma tu kotwicę, na którą wskazuje doc_url.

Błędy żądania (HTTP 4xx i 5xx)

parameter_missingHTTP 400invalid_request_error

Brakuje wymaganego parametru.

Co zrobić: Dodaj pole wskazane w param.

parameter_invalidHTTP 400invalid_request_error

Parametr ma zły typ lub format.

Co zrobić: Popraw pole z param; kwoty wysyłaj jako tekst, np. "49.00".

body_invalid_jsonHTTP 400invalid_request_error

Treść żądania nie jest poprawnym JSON.

Co zrobić: Serializuj treść biblioteką JSON i wyślij Content-Type: application/json.

body_too_largeHTTP 413invalid_request_error

Treść żądania ma ponad 1 MB.

Co zrobić: Wyślij mniej pozycji albo podziel zamówienie (do 1000 pozycji).

buyer_nip_missingHTTP 400invalid_request_error

Nabywca nie ma NIP; faktury KSeF wystawiamy tylko dla firm.

Co zrobić: Wysyłaj tylko zamówienia z NIP. Konsumentom faktura w KSeF nie jest potrzebna.

buyer_nip_invalidHTTP 400invalid_request_error

NIP nabywcy nie przechodzi polskiej sumy kontrolnej.

Co zrobić: Sprawdzaj NIP już w koszyku. Ręcznie: sprawdź NIP.

order_not_paidHTTP 400invalid_request_error

Zamówienie nie jest opłacone; fakturujemy tylko opłacone zamówienia.

Co zrobić: Wyślij zamówienie po potwierdzeniu płatności, z paid_at.

order_cancelledHTTP 400invalid_request_error

Zamówienie jest anulowane.

Co zrobić: Nie wysyłaj anulowanych zamówień.

currency_not_supportedHTTP 400invalid_request_error

Waluta nie ma kursu w tabeli A NBP.

Co zrobić: Użyj PLN albo waluty z tabeli A NBP. Waluty obce

vat_rate_missingHTTP 400invalid_request_error

Pozycja nie ma stawki VAT.

Co zrobić: Podaj vat_rate w każdej pozycji i dostawie. W WooCommerce sprawdź, czy dostawa jest opodatkowana.

vat_rate_unsupportedHTTP 400invalid_request_error

Stawka VAT inna niż 23, 8, 5 lub 0.

Co zrobić: Użyj 23, 8, 5 albo 0. Sprzedaż zwolniona (zw) nie jest jeszcze obsługiwana.

order_unprocessableHTTP 422invalid_request_error

Zamówienia nie da się zamienić w fakturę (szczegóły w message), np. ujemna opłata albo zwrot samej kwoty.

Co zrobić: Ujemne opłaty zamień na rabat na pozycji; zwrot opisz pozycjami lub dostawą. Korekty

correction_requires_invoiceHTTP 400invalid_request_error

Korektę tworzy się tylko do faktury (inv_...), nie do korekty.

Co zrobić: Wskaż id faktury pierwotnej w ścieżce.

livemode_mismatchHTTP 400invalid_request_error

Obiekt należy do drugiego trybu (testowy kontra produkcyjny).

Co zrobić: Użyj klucza z tego samego trybu, w którym powstał obiekt.

resource_missingHTTP 404not_found_error

Nie ma takiego obiektu albo należy do innego konta.

Co zrobić: Sprawdź id i czy klucz jest z właściwego konta i trybu.

route_not_foundHTTP 404not_found_error

Nieznany endpoint.

Co zrobić: Sprawdź ścieżkę z prefiksem /v1. Endpointy

method_not_allowedHTTP 405invalid_request_error

Endpoint nie obsługuje tej metody HTTP.

Co zrobić: Sprawdź metodę w referencji.

pdf_not_readyHTTP 409invalid_request_error

PDF renderuje się chwilę po przyjęciu faktury przez KSeF.

Co zrobić: Ponów za kilka sekund albo poczekaj na zdarzenie invoice.accepted.

api_key_missingHTTP 401authentication_error

Brak klucza API.

Co zrobić: Wyślij Authorization: Bearer sk_test_... albo sk_live_.... Uwierzytelnianie

api_key_invalidHTTP 401authentication_error

Klucz jest błędny, unieważniony albo konto jest wyłączone.

Co zrobić: Sprawdź, czy klucz nie został zmieniony w panelu; skopiuj nowy.

live_mode_disabledHTTP 403permission_error

Tryb produkcyjny nie jest jeszcze włączony dla tego konta.

Co zrobić: We wczesnym dostępie pracuj kluczem sk_test_. Tryb produkcyjny włączymy po starcie.

idempotency_key_reusedHTTP 409idempotency_error

Idempotency-Key użyto już z innym żądaniem.

Co zrobić: Nowa operacja to nowy klucz; ponowienie to ten sam klucz i ta sama treść. Idempotencja

idempotency_key_invalidHTTP 400idempotency_error

Idempotency-Key musi mieć 1-255 drukowalnych znaków.

Co zrobić: Użyj krótkiego tekstu, np. order-SO-1001.

rate_limitedHTTP 429rate_limit_error

Za dużo zapytań; czekaj Retry-After sekund.

Co zrobić: Odczekaj Retry-After sekund i ponów. Zamiast odpytywania użyj webhooków. Limity

internal_errorHTTP 500api_error

Coś poszło nie tak po naszej stronie.

Co zrobić: Ponów z tym samym Idempotency-Key. Gdy się powtarza, napisz z Request-Id na kontakt@ksefshop.pl.

Błędy dokumentu (pole last_error)

seller_not_configuredlast_errorinvoice_error

Brakuje NIP, nazwy lub adresu sprzedawcy w koncie.

Co zrobić: Uzupełnij dane sprzedawcy w panelu; sprawdzisz je przez GET /v1/account.

plan_limit_reachedlast_errorinvoice_error

Wyczerpany miesięczny limit planu; faktura czeka bez numeru, aż będzie miejsce.

Co zrobić: Faktura dostanie numer po zmianie planu albo w nowym miesiącu, bez luk w numeracji. Dotyczy tylko trybu produkcyjnego.

invoice_build_failedlast_errorinvoice_error

Z danych zamówienia nie da się zbudować faktury.

Co zrobić: Przeczytaj message, popraw dane i wyślij zamówienie z nowym external_id albo napisz do nas.

invoice_schema_invalidlast_errorinvoice_error

XML FA(3) nie przeszedł oficjalnego schematu XSD.

Co zrobić: Do KSeF nic nie poszło. Napisz do nas z id faktury.

original_not_invoicedlast_errorinvoice_error

Zamówienie nie ma faktury, którą można skorygować.

Co zrobić: Najpierw utwórz fakturę i poczekaj na accepted.

original_rejectedlast_errorinvoice_error

Faktura pierwotna została odrzucona przez KSeF, więc nie ma czego korygować.

Co zrobić: Wyjaśnij odrzucenie faktury pierwotnej; korekta nie jest potrzebna.

ksef_not_connectedlast_errorksef_error

Brak działającego certyfikatu lub tokenu KSeF dla tego trybu.

Co zrobić: Połącz KSeF w panelu. Certyfikat KSeF

ksef_auth_failedlast_errorksef_error

KSeF odrzucił certyfikat lub token (wygasł, unieważniony, brak uprawnień do NIP).

Co zrobić: Wygeneruj nowy certyfikat lub token w Aplikacji Podatnika KSeF i wgraj go w panelu.

ksef_duplicate_numberlast_errorksef_errorKSeF 440

KSeF 440: numer faktury jest już użyty przez inną fakturę tego sprzedawcy.

Co zrobić: Sprawdź, czy ten sam wzór numeracji nie jest używany w innym programie; zmień wzór w panelu.

ksef_rejectedlast_errorksef_errorKSeF 4xx

KSeF odrzucił fakturę; ksef_code i message zawierają kod i tekst KSeF.

Co zrobić: Przeczytaj kod KSeF. Gdy nie wiesz, co poprawić, napisz do nas z id faktury.

ksef_unavailablelast_errorksef_error

KSeF nie odpowiedział na czas; wysyłka ponawia się sama.

Co zrobić: Nic nie rób: kolejka ponawia wysyłkę. Status zmieni się sam.

Request-Id

Każda odpowiedź ma nagłówek Request-Id (np. req_8Kq2Lm4Np6Rs8Tu0Vw2X). Zapisuj go w logach i podawaj, pisząc do nas na kontakt@ksefshop.pl: po nim znajdziemy dokładnie to żądanie.