Limites de débit de l’API KSeF en 2026 : relances sûres en production

Les limites de débit de l’API KSeF s’appliquent simultanément par seconde, par minute et par heure, selon des fenêtres glissantes, généralement pour chaque paire (context, IP). Lorsque KSeF renvoie le code HTTP 429, attendez la durée indiquée par le serveur dans Retry-After, suspendez tous les processus d’exécution qui partagent ce quota et rapprochez les références de session ou de facture enregistrées avant de soumettre de nouveau une facture dont l’issue reste incertaine.

Cette dernière distinction est essentielle. Un code 429 vous indique quand réessayer. En revanche, si la connexion est interrompue après l’envoi d’une facture, vous ne savez pas si l’opération a abouti. Déclencher la même nouvelle tentative dans les deux cas risque de créer des doublons, de prolonger les blocages et de rendre la file d’attente moins stable à mesure que la charge augmente.

Ce guide relève de l’exploitation technique, et non du conseil fiscal ou juridique. Les valeurs ci-dessous correspondent aux contrats KSeF en vigueur, vérifiés le 28 août 2026.

Quelles limites de débit de l’API KSeF s’appliquent en production ?

KSeF fixe des seuils distincts, par seconde, par minute et par heure, pour chaque groupe d’opérations de l’API. Les trois seuils s’appliquent en même temps : le plafond horaire peut donc bloquer un client qui ne dépasse jamais son débit par seconde.

À la date de cette vérification, les environnements de production et DEMO utilisaient l’API 2.6.1. L’environnement TEST était en version 2.7.1, mais les groupes de points d’accès communs conservaient les mêmes valeurs par défaut. Les limites suivantes sont publiées dans le contrat OpenAPI de production en vigueur :

Il s’agit de valeurs par défaut, pas d’une constante de configuration à recopier une fois pour toutes dans l’application. Le point d’accès authentifié GET /rate-limits renvoie les valeurs effectives pour le contexte courant. KSeF peut ajuster les limites, accorder une augmentation individuelle ou accorder une hausse temporaire qui expirera ensuite. L’avis d’avril 2026 destiné aux intégrateurs du ministère précise que les modifications individuelles sont appliquées simultanément à DEMO et à la production.

Appuyez-vous sur le tableau statique pour planifier la capacité. Utilisez GET /rate-limits pour définir la politique d’exécution, mettez le résultat en cache et considérez qu’un véritable code 429 fait foi.

Deux chiffres obsolètes à retirer des anciens modes opératoires

Premièrement, les limites par défaut de TEST ne sont plus dix fois supérieures à celles de la production. Depuis l’API 2.5.0, TEST applique les mêmes limites que la production aux groupes communs, tout en conservant des points d’accès propres à TEST qui permettent aux intégrateurs de simuler des profils personnalisés. L’ancien facteur dix figure encore dans le guide textuel des limites, mais le journal des modifications de l’API et les contrats en vigueur confirment le changement ultérieur.

Deuxièmement, un PDF officiel indique encore une limite de quatre requêtes par seconde et huit par minute pour l’export de factures. L’API 2.4.0 a relevé ces seuils à huit et seize en production le 16 avril 2026. La limite horaire est restée fixée à 20.

Il faut donc tenir compte de la version. La branche main du dépôt contient déjà les modifications de l’API 2.7.1, déployées dans TEST le 26 août mais programmées en production pour le 23 septembre. Pour connaître le comportement actuel de la production, le contrat OpenAPI de production prime sur une modification de main qui n’y est pas encore déployée.

Comment KSeF comptabilise-t-il les requêtes ?

Les requêtes protégées sont normalement comptabilisées pour chaque combinaison d’un contexte KSeF et d’une adresse IP source. Les compteurs utilisent des fenêtres glissantes, et non des minutes ou des heures fixes.

Le guide officiel des limites de requêtes définit la clé de quota comme la paire formée par :

• le ContextIdentifier utilisé lors de l’authentification, par exemple Nip, InternalId ou NipVatUe ;
• l’adresse IP publique depuis laquelle le client se connecte.

Un même NIP utilisé derrière une seule adresse IP de sortie partage un budget entre tous les processus et toutes les tâches d’exécution qui passent par cette adresse. Un autre bureau ou intégrateur qui utilise le même contexte depuis une autre adresse IP dispose d’un compteur distinct. Les points d’accès publics sont protégés par adresse IP.

Chaque requête est comptée sur la seconde, les 60 secondes et les 60 minutes précédentes. Une fenêtre d’une minute ne revient pas à zéro à 12:01:00, pas plus qu’une fenêtre horaire au début de l’heure. Si vous consommez le budget de 20 exports de factures par heure au cours des dix premières minutes, attendre l’heure suivante ne suffit pas. La capacité se libère à mesure que ces appels sortent de la fenêtre glissante de 60 minutes.

Voilà aussi pourquoi une simple pause par processus ne suffit pas. Dix tâches d’exécution de l’application peuvent chacune se croire sous la limite alors que leur trafic cumulé dépasse le budget partagé de la paire (context, IP). Le régulateur de débit doit coordonner toutes les tâches qui utilisent la même clé de quota et le même groupe de limites.

N’utilisez pas une rotation des adresses IP pour contourner le dispositif. Le ministère indique explicitement qu’il consigne les infractions et surveille l’utilisation systématique de plusieurs adresses afin d’échapper aux limites. Des pratiques répétées ou extrêmes peuvent déclencher une protection plus large visant une entité ou une plage d’adresses IP.

Comment réagir après un code HTTP 429 ?

Après un code 429 Too Many Requests, lisez Retry-After, cessez d’envoyer des requêtes dans le flux soumis au quota concerné et attendez au moins la durée indiquée. Vous pouvez ajouter une courte temporisation aléatoire après le délai imposé par le serveur, jamais à sa place.

KSeF renvoie Retry-After sous la forme d’un nombre entier de secondes. Le blocage est dynamique et des infractions répétées peuvent l’allonger considérablement. Aucune valeur de repli codée en dur, comme « toujours réessayer après 30 secondes », ne peut donc être fiable.

Un ordonnanceur sûr suit cette séquence :

quota_key = [context_identifier, egress_ip, limit_group]

on HTTP 429:
  retry_after = parse Retry-After as seconds
  pause quota_key until monotonic_now + retry_after
  requeue the operation after pause_until + small_positive_jitter
  record the attempt and stop after a bounded retry/time budget

La suspension partagée est essentielle. Si vous ne remettez en file d’attente que la tâche qui a reçu la réponse, les autres continueront à solliciter le même quota. L’ajout d’une temporisation aléatoire relève aussi d’un choix d’ingénierie côté client, et non d’une exigence du ministère. Il permet d’échelonner la reprise des tâches après le délai obligatoire afin qu’elles ne redémarrent pas toutes à la même milliseconde.

KSeF prend en charge deux formats de corps d’erreur. L’ancienne réponse JSON reste disponible. Les clients peuvent demander le format Problem Details avec X-Error-Format: problem-details. Dans les deux cas, le moment de la nouvelle tentative dépend de l’en-tête de réponse. Votre couche HTTP doit donc préserver les en-têtes, même lorsqu’elle transforme le corps en exception typée.

Le client C# officiel analyse Retry-After et expose un délai recommandé. Son dépôt contient également un adaptateur de limitation de débit qui récupère les limites effectives, régule en amont selon les trois fenêtres et effectue jusqu’à cinq nouvelles tentatives pour une requête ayant reçu un code 429. Cet adaptateur se trouve dans les utilitaires de test, et non dans la chaîne de traitement du SDK de production. Le SDK Java expose lui aussi l’erreur et les en-têtes, mais n’installe pas de boucle générique de nouvelles tentatives automatiques.

Les deux clients intègrent un disjoncteur qui s’ouvre après cinq échecs transitoires consécutifs et autorise une requête d’essai en état semi-ouvert au bout de 30 secondes. Un disjoncteur n’est pas une politique de nouvelle tentative. Il rejette rapidement les appels pour protéger l’application et KSeF ; il ne renvoie pas la requête ayant échoué à votre place.

Quand faut-il réessayer, effectuer un rapprochement ou abandonner ?

Classez le résultat avant toute nouvelle tentative. Une limitation de débit, un traitement asynchrone en attente, des données invalides et une issue indéterminée après un incident réseau appellent chacun une réponse différente.

Ce tableau est volontairement plus strict que la consigne « réessayer après toute erreur transitoire ». Une requête GET arrivée à expiration peut généralement être répétée. Une requête POST ayant envoyé des octets avant la coupure de la connexion peut en revanche avoir déjà lancé une opération asynchrone.

Fixez un plafond de tentatives en plus du délai. Une file d’attente qui réessaie indéfiniment masque un incident et consomme la capacité nécessaire aux opérations saines. Une fois le nombre de tentatives ou le temps imparti épuisé, faites passer l’opération dans un état bloqué visible et alertez un opérateur en lui fournissant les données de corrélation nécessaires pour reprendre sans risque.

Comment éviter les soumissions de factures en double ?

La soumission de factures à KSeF n’est pas documentée comme idempotente. Enregistrez durablement une tentative locale, l’empreinte du contenu, la référence de session et la référence de facture, puis rapprochez tout résultat incertain avant de créer une nouvelle soumission.

Le contrat KSeF ne prévoit ni en-tête Idempotency-Key ni jeton de requête client pour l’envoi d’une facture. L’empreinte SHA-256 de la facture sert à garantir son intégrité et à établir une corrélation ; elle n’est pas documentée comme clé d’idempotence.

Utilisez une machine à états locale et persistante :

1. Créez la tentative avant la requête. Enregistrez l’identifiant de la facture source, l’empreinte exacte de la charge utile, le contexte, l’environnement, le type d’opération et le numéro de tentative.
2. Enregistrez les références sans délai. L’ouverture d’une session en ligne renvoie une referenceNumber de session. L’envoi d’une facture renvoie un code HTTP 202 accompagné d’une autre referenceNumber, propre à la facture. Enregistrez chacune d’elles avant de planifier l’étape suivante.
3. Distinguez la soumission de l’acceptation. Une réponse HTTP réussie signifie que KSeF a accepté de traiter l’opération. Elle ne signifie pas encore qu’un numéro KSeF a été attribué à la facture.
4. Rapprochez les opérations d’écriture dont l’issue est incertaine. Si vous ne recevez pas la réponse, inspectez la session connue, ses factures et les empreintes enregistrées. Si une référence de facture existe, interrogez son état.
5. Ne créez une nouvelle tentative qu’après le rapprochement. Conservez la tentative précédente et indiquez pourquoi il a fallu rejouer l’opération.

Le guide officiel du traitement par lots recommande précisément de conserver une correspondance locale entre l’empreinte SHA-256 de chaque fichier XML d’origine et son document source. Les enregistrements de facture renvoyés par la session contiennent l’empreinte, la référence, le numéro de facture, l’état et, le cas échéant, le numéro KSeF. Vous disposez ainsi des éléments nécessaires pour faire correspondre les résultats sans approximation.

KSeF détecte également les doublons de manière globale à partir du NIP du vendeur, du type de facture et de son numéro. Un doublon reçoit l’état asynchrone 440, et non une nouvelle confirmation de soumission. La réponse actuelle peut contenir originalSessionReferenceNumber et originalKsefNumber. Ces champs facilitent la réparation de l’état lorsqu’un doublon apparaît, mais ne rendent pas l’opération idempotente pour autant.

Comment cadencer les interrogations d’état et les traitements par lots ?

Attribuez à chaque groupe de limites KSeF son propre flux régulé de manière coordonnée, conservez une marge sous chaque seuil glissant et privilégiez les opérations par lots lorsque plusieurs factures sont prêtes dans une même fenêtre opérationnelle.

Commencez par un régulateur de débit indexé sur (context, egress IP, limit group). Chargez les valeurs effectives depuis GET /rate-limits, mettez-les en cache et actualisez-les périodiquement. N’appelez pas le point d’accès des limites avant chaque requête, car il s’agit lui aussi d’une opération de l’API.

Séparez ensuite les types d’opérations suivants :

• gestion des sessions en ligne ;
• envois interactifs de factures ;
• interrogation de l’état des factures ;
• création des exports et interrogation de leur état ;
• téléchargement des factures ;
• autres opérations protégées.

Conservez volontairement une marge. Un ordonnanceur qui vise exactement 30 envois par minute ne laisse aucune place à un décalage d’horloge, à l’exécution tardive d’une tâche, à une autre instance de l’application ou à du trafic manuel utilisant les mêmes NIP et adresse IP.

Réservez un budget propre à l’interrogation des états. Le point d’accès à l’état d’une facture autorise 120 appels par minute et 1 200 par heure, tandis que la liste de toutes les sessions n’en autorise que 10 par minute et 60 par heure. Interrogez la référence précise que vous connaissez déjà au lieu de demander sans cesse la liste complète. Espacez davantage les appels tant que l’état vaut 100 ou 150, ajoutez une temporisation aléatoire, plafonnez le délai et arrêtez-vous à l’obtention d’un résultat terminal ou à l’échéance opérationnelle.

Pour plusieurs factures, le ministère recommande le mode par lots. Un lot de 100 factures consomme généralement moins de capacité de requête que 100 envois interactifs. Les différentes parties du lot peuvent être téléversées en parallèle dans une session par lots ouverte, sans être soumises aux limites de requêtes de l’API. L’ouverture et la fermeture de la session restent toutefois des opérations limitées.

Le même principe vaut pour la récupération. KSeF indique que les systèmes à fort volume doivent utiliser les exports asynchrones de factures et synchroniser les données dans une base locale. Appeler KSeF chaque fois qu’un utilisateur ouvre une facture revient à transformer un référentiel central en base de données applicative et gaspille un quota de téléchargement déjà limité.

Que faut-il surveiller en production ?

Surveillez la consommation des quotas, les décisions de nouvelle tentative, les résultats asynchrones et l’état de récupération sans consigner le contenu des factures ni les identifiants de connexion. Compter les seuls codes 429 vous indique que le système a pris du retard, mais pas pourquoi.

Enregistrez au minimum :

• les limites effectives et l’heure de leur dernière actualisation ;
• le nombre de requêtes par environnement, contexte, adresse IP de sortie et groupe de limites ;
• le nombre de codes 429, la valeur de Retry-After, le numéro de tentative et le résultat final ;
• la profondeur et l’ancienneté des files d’attente pour les envois, les vérifications d’état, les exports et les téléchargements ;
• le délai entre la soumission et l’état terminal de la facture ;
• le nombre d’états en attente 100/150, de doublons 440 et d’annulations 550 ;
• les écritures à l’issue inconnue en attente de rapprochement ;
• l’état du disjoncteur et les appels rejetés ;
• les références de session, de facture, d’export et de tentative locale nécessaires à l’assistance.

Écartez les champs sensibles des journaux et des outils de suivi des erreurs. Le XML des factures, les données des acheteurs, les jetons d’authentification, les documents UPO, les cookies et les paramètres bruts des requêtes n’ont rien à faire dans un événement d’exception. Les identifiants, les changements d’état, la classe de réponse, l’identifiant de trace et les durées suffisent généralement à diagnostiquer l’échec d’une nouvelle tentative.

Déclenchez des alertes sur les tendances, pas seulement sur les réponses individuelles. Une estimation croissante de la consommation du budget horaire, une file d’attente des états qui s’allonge ou des valeurs Retry-After élevées et répétées vous donnent le temps de ralentir les producteurs avant que l’intégration ne s’enferme dans une tempête de nouvelles tentatives.

Comment KSeF Kit gère-t-il actuellement les nouvelles tentatives ?

KSeF Kit utilise des tentatives de soumission persistantes et conserve les références KSeF afin de pouvoir reprendre l’interrogation des états sans renvoyer aveuglément la même facture. Sa documentation publique décrit cinq tentatives, espacées par des délais croissants, pour les échecs transitoires 429, 500 et 550.

Le cycle de dépôt prend pour source immuable une facture Stripe finalisée, la convertit en FA(3), ouvre une session en ligne, la soumet, puis interroge KSeF jusqu’à obtenir le numéro KSeF et l’UPO. Chaque tentative de soumission fait l’objet d’un enregistrement distinct. Si l’interrogation est interrompue, les références conservées permettent à une tâche ultérieure de reprendre à partir de l’opération acceptée.

Le guide de l’API KSeF et le mode opératoire en cas de panne distinguent les nouvelles tentatives après une erreur transitoire du rapprochement. Les états présentés à l’utilisateur différencient les opérations en file d’attente, en cours de soumission, acceptées, rejetées et bloquées. La documentation sur la sécurité précise que les erreurs enregistrées dans Sentry contiennent des identifiants et l’état, mais excluent le contenu des factures, les données personnelles des acheteurs, les jetons, les UPO, les paramètres de requête et les cookies.

Tel est le périmètre actuel du produit. KSeF Kit ne prétend pas publiquement proposer des budgets de requêtes par contexte, une politique de temporisation aléatoire documentée, des tableaux de suivi des limites de débit ou l’émission offline24. L’architecture plus large décrite dans ce guide constitue le modèle à viser pour une intégration de production robuste, et non l’énumération de fonctionnalités cachées du produit.

La règle d’exploitation tient en une phrase : cadencez vos appels avant que KSeF ne doive vous arrêter, respectez le délai lorsqu’il le fait et ne confondez jamais une nouvelle tentative après un incident de transport avec la vérification de l’existence d’une facture.