Przejdź do głównej treści
KSeF 2.0 · API

KSeF HTTP 429, 403 i 401: limity zapytań i odmowa dostępu

Te trzy odpowiedzi nie mają pięciocyfrowego kodu KSeF, bo to zwykłe kody HTTP. Mają jednak swoje reguły: 429 przychodzi z nagłówkiem Retry-After, 403 z polem reasonCode, które mówi, czego brakuje, a 401 oznacza, że token dostępu wygasł.

FlexigoTech · Odpowiada: Víctor Gómez · Aktualizacja: 5 listopada 2026

Najważniejsze

Moduł
KSeF 2.0
Wersje
Odoo 17, 18, 19 i 20
Sprawdzone
w źródłach podanych na końcu
Czas czytania
2 min

Limit zapytań: 429

Po przekroczeniu limitu KSeF odpowiada HTTP 429 „Too Many Requests” z nagłówkiem Retry-After i blokuje dostęp do API na wskazany czas. Przykład z dokumentacji: „Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach.”. Limity liczy się na sekundę, minutę i godzinę. Wyższe limity w godzinach 20:00-06:00 dotyczą tylko pobierania, a ich wartości nie zostały jeszcze podane. Wysyłka faktur nie ma w nocy wyższych limitów.

Najważniejsze dla wysyłki z Odoo:

  • wysłanie faktury: 10 na sekundę, 30 na minutę, 180 na godzinę;
  • otwarcie sesji interaktywnej: 10, 30 i 120;
  • status faktury z sesji: 30, 120 i 1200;
  • pozostałe zapytania: 10, 30 i 120.
Karta kodów HTTP 429, 403 i 401 w KSeF
429 z tekstem z API oraz 401 i 403, które przychodzą bez kodu KSeF.

Odmowa dostępu: 403 i jego reasonCode

reasonCodeTekst KSeF
missing-permissions„Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.”
ip-not-allowed„Żądanie pochodzi z adresu IP innego niż wskazany podczas uwierzytelnienia.”
insufficient-resource-access„Brak dostępu do wskazanego zasobu.”
auth-method-not-allowed„Ta operacja nie jest dostępna dla użytej metody uwierzytelnienia.”
security-service-blocked„Żądanie zostało zablokowane przez mechanizmy bezpieczeństwa.”
context-type-not-allowed„Operacja nie jest dostępna dla uwierzytelnionego typu kontekstu.”

Odpowiedzi 401 i 403 przychodzą w formacie Problem Details, a 400 i 429 też mogą, jeśli program wyśle nagłówek X-Error-Format: problem-details. Odoo go nie wysyła.

Co robi Odoo 18, 19 i 20

Przy 401 Odoo odświeża token dostępu i powtarza zapytanie jeden raz. Przy 403 pokazuje „KSeF API Error: ” z treścią odpowiedzi, więc reasonCode zobaczysz w komunikacie. Przy 429 zgłasza błąd „Too Many Requests”:

  • przy wysyłce faktura dostaje ten błąd i zostaje bez stanu KSeF, a Retry-After nie jest brany pod uwagę: wyślij ją ponownie po chwili;
  • pobieranie faktur zakupowych, które Odoo robi co 3 godziny, czyta Retry-After i samo planuje się na później.

Po wysyłce Odoo pyta o status do 5 razy co 2 sekundy. Przy wielu fakturach wysłanych naraz to też są zapytania, które wliczają się do limitu statusu.

Schemat: co zwraca KSeF przy odpowiedziach HTTP 429, 403 i 401 i co pokazuje Odoo 20
Schemat na podstawie kodu l10n_pl_edi z Odoo 20 i specyfikacji API KSeF 2.9.0; skreślone jest to, czego Odoo nie zapisuje albo nie robi.

Jak uniknąć 429

Faktura z błędem „Too Many Requests” nie ma stanu KSeF, bo KSeF nie przyjął zapytania, więc wróci na listę do wysłania i nie ma ryzyka, że trafi do KSeF dwa razy. Wysyłaj faktury mniejszymi partiami i nie klikaj ponownej wysyłki seriami. Jeśli regularnie dochodzisz do limitów wysyłki w sesji interaktywnej, Ministerstwo Finansów radzi najpierw rozważyć tryb wsadowy, a gdy sesja interaktywna jest niezbędna, zgłosić się do wsparcia KSeF. Odoo wysyła faktury tylko w sesji interaktywnej. Nasz moduł, Poland KSeF 2.0 Validator, nie wysyła zapytań do KSeF, więc nie zużywa tych limitów; z subskrypcją jego walidacja FA(3) idzie do FlexigoTech Cloud.

Czy 403 security-service-blocked minie sam?

Dokumentacja mówi tylko, że zapytanie zablokowały mechanizmy bezpieczeństwa. Jeśli powtarza się przy poprawnych danych, zgłoś to do wsparcia KSeF.

Czytaj dalej

Wyjątki KSeF przy wysyłce faktury: 21405, 21180, 21184 i resztaWyjątki KSeF przy wysyłce faktury: 21405, 21001, 21155, 21166, 21167, 21173, 21180, 21184, 21402 i 21403. Co znaczą i jak je widać w Odoo 18, 19 i 20.Statusy uwierzytelniania KSeF: 415, 425, 450, 470 i 480Statusy logowania do KSeF 2.0 poza certyfikatem: brak uprawnień, unieważnienie, zły token, blokada. Kody 21301 i 21304 i jak to wygląda w Odoo 18-20.Kody 410 i 415 w KSeF: uprawnienia sprzedawcy i załącznikiKod 410 „Nieprawidłowy zakres uprawnień” i 415 „Brak możliwości wysyłania faktury z załącznikiem”: co je wywołuje według testów MF i co sprawdzić w Odoo 18, 19 i 20.
Sprawdzone w podlinkowanych źródłach

Źródła