Vai al contenuto principale
KSeF 2.0 · API

KSeF HTTP 429, 403 e 401: limiti di richieste e accesso negato

Queste tre risposte non hanno un codice KSeF di cinque cifre, perché sono codici HTTP normali. Seguono comunque delle regole: il 429 arriva con l'intestazione Retry-After, il 403 con un campo reasonCode che indica cosa manca e il 401 significa che il token di accesso è scaduto.

FlexigoTech · Responsabile: Víctor Gómez · Aggiornato il 5 novembre 2026

In breve

Modulo
KSeF 2.0
Versioni
Odoo 17, 18, 19 e 20
Verificato
nelle fonti collegate in fondo
Lettura
3 min

Limite di richieste: 429

Oltre il limite, KSeF risponde con HTTP 429 «Too Many Requests» con l'intestazione Retry-After e blocca l'accesso alle API per il tempo indicato. L'esempio della documentazione: «Przekroczono limit 20 żądań na minutę. Spróbuj ponownie po 30 sekundach.» (superato il limite di 20 richieste al minuto; riprova dopo 30 secondi). I limiti si contano per secondo, minuto e ora. I limiti più alti tra le 20:00 e le 06:00 valgono solo per il download e non sono ancora stati pubblicati valori; l'invio delle fatture non ha limiti più alti di notte.

Ciò che conta di più quando si invia da Odoo:

  • invio di una fattura: 10 al secondo, 30 al minuto, 180 all'ora;
  • apertura di una sessione interattiva: 10, 30 e 120;
  • stato di una fattura nella sessione: 30, 120 e 1200;
  • altre richieste: 10, 30 e 120.
Scheda dei codici HTTP 429, 403 e 401 di KSeF
Il 429 con il testo dell'API, e il 401 e il 403, che arrivano senza codice KSeF.

Accesso negato: il 403 e il suo reasonCode

reasonCodeTesto di KSeF
missing-permissions«Brak wymaganych uprawnień do wykonania operacji w bieżącym kontekście.» (mancano i permessi nel contesto attuale)
ip-not-allowed«Żądanie pochodzi z adresu IP innego niż wskazany podczas uwierzytelnienia.» (la richiesta proviene da un IP diverso da quello indicato all'accesso)
insufficient-resource-access«Brak dostępu do wskazanego zasobu.» (nessun accesso a quella risorsa)
auth-method-not-allowed«Ta operacja nie jest dostępna dla użytej metody uwierzytelnienia.» (non disponibile con quel metodo di accesso)
security-service-blocked«Żądanie zostało zablokowane przez mechanizmy bezpieczeństwa.» (bloccata dai meccanismi di sicurezza)
context-type-not-allowed«Operacja nie jest dostępna dla uwierzytelnionego typu kontekstu.» (non disponibile per quel tipo di contesto)

Le risposte 401 e 403 arrivano nel formato Problem Details, e anche le 400 e le 429 possono arrivarci se il programma invia l'intestazione X-Error-Format: problem-details. Odoo non la invia.

Cosa fanno Odoo 18, 19 e 20

Di fronte a un 401, Odoo aggiorna il token di accesso e ripete la richiesta una volta. Di fronte a un 403 mostra «KSeF API Error: » con il corpo della risposta, quindi nel messaggio vedrai il reasonCode. Di fronte a un 429 genera l'errore «Too Many Requests»:

  • all'invio, la fattura riceve quell'errore e resta senza stato KSeF, e Retry-After non viene considerato: rinviala un po' più tardi;
  • il download delle fatture fornitore, che Odoo esegue ogni 3 ore, legge Retry-After e si riprogramma da sola.

Dopo l'invio, Odoo chiede lo stato fino a 5 volte, a distanza di 2 secondi. Con molte fatture inviate in una volta, anche quelle richieste contano per il limite di stato.

Schema: cosa restituisce KSeF con le risposte HTTP 429, 403 e 401 e cosa mostra Odoo 20
Schema realizzato a partire dal codice di l10n_pl_edi di Odoo 20 e dalla specifica dell'API KSeF 2.9.0; ciò che è barrato è ciò che Odoo non conserva o non fa.

Come evitare il 429

Una fattura con l'errore «Too Many Requests» non ha stato KSeF, perché KSeF non ha accettato la richiesta, quindi torna tra le fatture da inviare e non c'è rischio che arrivi due volte a KSeF. Invia le fatture in gruppi più piccoli e non premere ripetutamente reinvia. Se raggiungi spesso i limiti di invio della sessione interattiva, il Ministero delle Finanze consiglia di valutare prima la modalità a lotti e, se la sessione interattiva è indispensabile, di scrivere al supporto di KSeF. Odoo invia fatture solo in sessione interattiva. Il nostro modulo, Poland KSeF 2.0 Validator, non fa richieste a KSeF, quindi non consuma questi limiti; con l'abbonamento, la sua validazione del FA(3) avviene su FlexigoTech Cloud.

Un 403 security-service-blocked si risolve da solo?

La documentazione dice solo che la richiesta è stata bloccata dai meccanismi di sicurezza. Se si ripete con dati corretti, segnalalo al supporto di KSeF.

Continua a leggere

Eccezioni di KSeF all'invio di una fattura: 21405, 21180, 21184 e le altreEccezioni di KSeF all'invio di una fattura: 21405, 21001, 21155, 21166, 21167, 21173, 21180, 21184, 21402 e 21403. Cosa significano e come si vedono in Odoo.Stati di autenticazione KSeF: 415, 425, 450, 470 e 480Stati dell'accesso a KSeF 2.0 diversi dal certificato: senza permessi, revocato, token errato, bloccato. Codici 21301 e 21304 e come appaiono in Odoo.Codici 410 e 415 di KSeF: permessi del venditore e allegatiIl 410 «Nieprawidłowy zakres uprawnień» e il 415 per le fatture con allegato: cosa li causa nei test del Ministero e cosa controllare in Odoo 18, 19 e 20.
Verificato nelle fonti collegate

Fonti