KSeF-API-Limits 2026: Sicher im Produktivbetrieb wiederholen

Die KSeF-API-Limits gelten gleichzeitig pro Sekunde, Minute und Stunde in gleitenden Zeitfenstern, in der Regel für jedes Paar (context, IP). Antwortet KSeF mit HTTP 429, warten Sie die vom Server im Feld Retry-After vorgegebene Zeit, pausieren Sie alle Worker mit demselben Kontingent und gleichen Sie gespeicherte Sitzungs- oder Rechnungsreferenzen ab, bevor Sie eine Übermittlung mit ungewissem Ausgang wiederholen.

Diese Unterscheidung ist wichtig. Eine 429-Antwort sagt Ihnen, wann Sie es erneut versuchen können. Bricht die Verbindung nach dem Senden einer Rechnung ab, ist der Ausgang dagegen ungewiss. Wenn Sie beide Fälle gleich behandeln und pauschal wiederholen, riskieren Sie doppelte Übermittlungen, längere Sperren und eine Warteschlange, die unter Last immer instabiler wird.

Dieser Artikel ist ein technischer Betriebsleitfaden, keine Steuer- oder Rechtsberatung. Die folgenden Werte entsprechen den produktiven KSeF-API-Verträgen, die am 28. August 2026 geprüft wurden.

Welche KSeF-API-Limits gelten im Produktivbetrieb?

KSeF weist Gruppen von API-Vorgängen eigene Grenzwerte pro Sekunde, Minute und Stunde zu. Alle drei gelten gleichzeitig. Deshalb kann das Stundenlimit einen Client stoppen, der sein Sekundenlimit nie überschreitet.

Zum Stichtag liefen Produktion und DEMO mit API 2.6.1. TEST verwendete 2.7.1, für gemeinsame Endpunktgruppen galten jedoch dieselben Standardwerte. Diese Limits nennt der produktive OpenAPI-Vertrag:

Das sind Standardwerte, keine Konfigurationswerte, die Sie dauerhaft in Ihre Anwendung übernehmen sollten. Der authentifizierte Endpunkt GET /rate-limits liefert die für den aktuellen Kontext gültigen Werte. KSeF kann Limits anpassen, individuell erhöhen oder vorübergehend anheben und später wieder zurücksetzen. Laut der Mitteilung für Integratoren vom April 2026 wendet das Ministerium individuelle Änderungen gleichzeitig auf DEMO und Produktion an.

Nutzen Sie die statische Tabelle für Ihre Kapazitätsplanung. Rufen Sie für die laufende Steuerung GET /rate-limits ab, speichern Sie das Ergebnis zwischen und behandeln Sie einen tatsächlich empfangenen 429-Status als maßgeblich.

Zwei veraltete Angaben, die Sie aus alten Betriebshandbüchern streichen sollten

Erstens liegen die Standardlimits in TEST nicht mehr zehnmal so hoch wie in der Produktion. Mit API 2.5.0 wurden die Werte gemeinsamer Gruppen an die Produktion angeglichen. TEST-spezifische Endpunkte, über die Integratoren eigene Profile simulieren können, blieben erhalten. Der veraltete Faktor 10× steht noch im beschreibenden Leitfaden zu den Limits, doch das API-Änderungsprotokoll und die produktiven API-Verträge dokumentieren die spätere Änderung.

Zweitens nennt ein offizielles PDF für Rechnungsexporte noch 4 Anfragen pro Sekunde und 8 pro Minute. Mit API 2.4.0 wurden diese Grenzwerte am 16. April 2026 in der Produktion auf 8 und 16 erhöht. Das Stundenlimit blieb bei 20.

Die Version spielt hier eine entscheidende Rolle. Der Branch main im Repository enthält bereits Änderungen für API 2.7.1, die am 26. August in TEST bereitgestellt wurden, für die Produktion aber erst am 23. September vorgesehen waren. Für das heutige Verhalten der Produktion ist der produktive OpenAPI-Vertrag maßgeblich, nicht ein künftiger Eintrag auf main.

Wie zählt KSeF Anfragen?

Geschützte Anfragen werden normalerweise für jede Kombination aus KSeF-Kontext und Quell-IP separat gezählt. Die Zähler arbeiten mit gleitenden Zeitfenstern, nicht mit festen Minuten- oder Stundenblöcken nach der Uhrzeit.

Der offizielle Leitfaden zu Anfragelimits definiert den Kontingentschlüssel als Paar aus:

• dem bei der Authentifizierung verwendeten ContextIdentifier, etwa Nip, InternalId oder NipVatUe;
• der öffentlichen IP-Adresse, über die sich der Client verbindet.

Wird dieselbe NIP über eine einzige ausgehende IP-Adresse verwendet, teilen sich alle Prozesse und Worker hinter dieser Adresse ein Kontingent. Ein anderes Büro oder ein anderer Integrator, der denselben Kontext über eine andere IP-Adresse nutzt, erhält einen separaten Zähler. Bei öffentlichen Endpunkten dient die IP-Adresse als Kontingentschlüssel.

Jede Anfrage fließt in die Zählung der vergangenen Sekunde, der vergangenen 60 Sekunden und der vergangenen 60 Minuten ein. Ein Minutenfenster wird nicht um 12:01:00 zurückgesetzt, ein Stundenfenster nicht zur vollen Stunde. Wenn Sie das Kontingent von 20 Rechnungsexporten pro Stunde in den ersten zehn Minuten ausschöpfen, reicht es nicht, bis zur nächsten vollen Stunde zu warten. Kapazität wird erst wieder frei, wenn die jeweiligen Aufrufe aus dem gleitenden 60-Minuten-Fenster fallen.

Deshalb genügt auch eine einfache Pause pro Prozess nicht. Zehn Anwendungs-Worker können jeweils davon ausgehen, dass sie das Limit einhalten, während ihr Gesamtverkehr das gemeinsame Kontingent für (context, IP) überschreitet. Die Begrenzung muss alle Worker koordinieren, die denselben Kontingentschlüssel und dieselbe Limitgruppe verwenden.

Versuchen Sie nicht, das Limit durch wechselnde IP-Adressen zu umgehen. Das Ministerium weist ausdrücklich darauf hin, dass es Verstöße protokolliert und die systematische Nutzung mehrerer Adressen zur Umgehung der Limits überwacht. Wiederholte oder besonders starke Verstöße können umfassendere Schutzmaßnahmen für einen Steuerpflichtigen oder einen IP-Adressbereich auslösen.

Wie sollte Ihre Integration auf HTTP 429 reagieren?

Lesen Sie bei 429 Too Many Requests den Wert Retry-After, senden Sie für die betroffene Limitgruppe vorerst keine weiteren Anfragen und warten Sie mindestens die angegebene Zahl von Sekunden. Nach der vom Server vorgegebenen Wartezeit können Sie eine kleine positive Zufallsverzögerung hinzufügen, niemals anstelle dieser Wartezeit.

KSeF gibt Retry-After als ganze Zahl von Sekunden zurück. Die Sperrdauer ist dynamisch und kann bei wiederholten Verstößen deutlich steigen. Einen allgemeingültigen, fest einprogrammierten Ersatzwert wie „immer nach 30 Sekunden wiederholen“ gibt es nicht.

Ein sicherer Scheduler hält sich an diesen Ablauf:

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

Die gemeinsame Pause ist entscheidend. Wenn Sie nur den Worker erneut einreihen, der die Antwort erhalten hat, senden die übrigen Worker weiter Anfragen zulasten desselben Kontingents. Die zusätzliche Zufallsverzögerung ist außerdem eine technische Entscheidung auf Clientseite, keine Vorgabe des Ministeriums. Sie verteilt die wartenden Worker nach Ablauf der vorgeschriebenen Wartezeit, damit nicht alle in derselben Millisekunde wieder aktiv werden.

KSeF unterstützt zwei Formate für Fehlerantworten. Die bisherige JSON-Antwort bleibt verfügbar. Clients können mit X-Error-Format: problem-details Problem Details anfordern. In beiden Fällen bestimmt der Antwort-Header den Zeitpunkt des nächsten Versuchs. Ihre HTTP-Schicht sollte Header daher auch dann erhalten, wenn sie den Antworttext in eine typisierte Ausnahme umwandelt.

Der offizielle C#-Client wertet Retry-After aus und stellt eine empfohlene Wartezeit bereit. Sein Repository enthält außerdem einen Wrapper für API-Limits. Dieser ruft die gültigen Limits ab, drosselt Anfragen vorab anhand aller drei Zeitfenster und wiederholt einen 429-Status bis zu fünfmal. Der Wrapper gehört jedoch zu den Testwerkzeugen und nicht zur produktiven SDK-Pipeline. Auch das Java-SDK stellt Fehler und Header bereit, richtet aber keine allgemeine automatische Wiederholung ein.

Beide Clients enthalten einen Circuit Breaker, der nach fünf aufeinanderfolgenden vorübergehenden Fehlern öffnet und nach 30 Sekunden einen Prüfaufruf im halboffenen Zustand zulässt. Ein Circuit Breaker ist keine Wiederholungsstrategie. Er bricht schnell ab, um die Anwendung und KSeF zu schützen. Die fehlgeschlagene Anfrage sendet er nicht erneut.

Welche Fehler sollten Sie wiederholen, abgleichen oder endgültig stoppen?

Klassifizieren Sie den Ausgang, bevor Sie eine Anfrage wiederholen. API-Limits, noch laufende asynchrone Verarbeitung, ungültige Eingaben und ein unbekannter Netzwerkausgang erfordern jeweils eine andere Reaktion.

Diese Tabelle ist bewusst strenger als die Regel „jeden vorübergehenden Fehler erneut versuchen“. Eine GET-Anfrage mit Zeitüberschreitung lässt sich in der Regel gefahrlos wiederholen. Bei einer POST-Anfrage, die vor dem Verbindungsabbruch bereits Daten übertragen hat, kann ein asynchroner Vorgang dagegen schon gestartet worden sein.

Begrenzen Sie nicht nur die Wartezeit, sondern auch die Zahl der Wiederholungen. Eine Warteschlange, die Vorgänge endlos wiederholt, verschleiert einen Vorfall und verbraucht Kapazität, die für fehlerfreie Arbeit benötigt wird. Ist das Budget für Versuche oder die verstrichene Zeit ausgeschöpft, versetzen Sie den Vorgang in den sichtbaren Status „blockiert“. Informieren Sie die zuständige Person und liefern Sie die Korrelationsdaten mit, die für eine sichere Fortsetzung nötig sind.

Wie verhindern Sie doppelte Rechnungsübermittlungen?

Die Übermittlung von Rechnungen an KSeF ist nicht als idempotent dokumentiert. Speichern Sie einen lokalen Versuch, den Hash des Inhalts sowie die Sitzungs- und Rechnungsreferenz dauerhaft. Gleichen Sie einen ungewissen Ausgang ab, bevor Sie eine weitere Übermittlung anlegen.

Der KSeF-Vertrag stellt für Rechnungsübermittlungen weder einen Idempotency-Key-Header noch ein Client-Anfrage-Token bereit. Der SHA-256-Hash der Rechnung dient der Integrität und Korrelation. Als Idempotenzschlüssel ist er nicht dokumentiert.

Verwenden Sie einen dauerhaft gespeicherten lokalen Zustandsautomaten:

1. Legen Sie den Versuch vor der Anfrage an. Speichern Sie die ID der Ausgangsrechnung, den exakten Hash der Nutzdaten, Kontext, Umgebung, Vorgangstyp und Versuchsnummer.
2. Speichern Sie Referenzen sofort. Beim Öffnen einer Online-Sitzung erhalten Sie eine Sitzungs-referenceNumber. Das Senden einer Rechnung liefert HTTP 202 und eine separate referenceNumber für die Rechnung. Speichern Sie beide, bevor Sie den nächsten Schritt einplanen.
3. Unterscheiden Sie zwischen übermittelt und angenommen. Eine erfolgreiche HTTP-Antwort bedeutet, dass KSeF den Vorgang zur Verarbeitung angenommen hat. Die Rechnung hat zu diesem Zeitpunkt noch nicht zwingend eine KSeF-Nummer erhalten.
4. Gleichen Sie Schreibvorgänge mit ungewissem Ausgang ab. Geht die Antwort verloren, prüfen Sie die bekannte Sitzung, die enthaltenen Rechnungen und gespeicherten Hashes. Ist eine Rechnungsreferenz vorhanden, fragen Sie deren Status ab.
5. Legen Sie einen neuen Versuch erst nach dem Abgleich an. Bewahren Sie den vorherigen Versuch auf und dokumentieren Sie, warum eine Wiederholung nötig war.

Der offizielle Leitfaden zur Stapelverarbeitung empfiehlt ausdrücklich eine lokale Zuordnung des SHA-256-Hashes jeder ursprünglichen XML-Datei zu ihrem Quelldokument. Zurückgegebene Datensätze zu Sitzungsrechnungen enthalten Hash, Referenz, Rechnungsnummer, Status und optional die KSeF-Nummer. Damit können Sie Ergebnisse zweifelsfrei zuordnen.

KSeF erkennt doppelte Rechnungen außerdem systemweit anhand der NIP des Verkäufers, des Rechnungstyps und der Rechnungsnummer. Ein Duplikat erhält den asynchronen Status 440, statt erneut erfolgreich übermittelt zu werden. Die aktuelle Antwort kann originalSessionReferenceNumber und originalKsefNumber enthalten. Mit diesen Feldern können Sie den Zustand nach einem Duplikat korrigieren. Sie machen die Wiederholung jedoch nicht zu einem idempotenten Vorgang.

Wie sollten Sie Abfragen und Stapelverarbeitung takten?

Geben Sie jeder KSeF-Limitgruppe einen eigenen koordinierten Ausführungspfad, planen Sie unterhalb jedes gleitenden Grenzwerts Reserven ein und bevorzugen Sie Stapelvorgänge, wenn im selben Betriebsfenster mehrere Rechnungen bereitstehen.

Beginnen Sie mit einer zentral koordinierten Drosselung, deren Schlüssel aus (context, egress IP, limit group) besteht. Laden Sie die gültigen Werte über GET /rate-limits, speichern Sie sie zwischen und aktualisieren Sie sie regelmäßig. Rufen Sie den Limit-Endpunkt nicht vor jeder Anfrage auf, denn auch dieser Aufruf ist ein API-Vorgang.

Trennen Sie anschließend diese Arbeitslasten:

• Steuerung von Online-Sitzungen;
• interaktive Rechnungsübermittlungen;
• Statusabfragen für Rechnungen;
• Anlegen von Exporten und Abfragen ihres Status;
• Herunterladen von Rechnungen;
• sonstige geschützte Vorgänge.

Planen Sie bewusst Reserven ein. Ein Scheduler, der genau 30 Übermittlungen pro Minute anstrebt, lässt keinen Spielraum für Uhrzeitabweichungen, verzögert gestartete Jobs, eine weitere Anwendungsinstanz oder manuellen Datenverkehr mit derselben NIP und IP-Adresse.

Auch Statusabfragen brauchen ein eigenes Budget. Ein Endpunkt für den Rechnungsstatus erlaubt 120 Aufrufe pro Minute und 1.200 pro Stunde, während die Liste aller Sitzungen nur 10 Aufrufe pro Minute und 60 pro Stunde zulässt. Fragen Sie die konkrete, bereits bekannte Referenz ab, statt immer wieder sämtliche Daten aufzulisten. Vergrößern Sie das Intervall, solange der Status 100 oder 150 lautet, fügen Sie eine Zufallsverzögerung hinzu und begrenzen Sie die maximale Wartezeit. Stoppen Sie bei einem Endstatus oder nach Ablauf einer betrieblichen Frist.

Für mehrere Rechnungen empfiehlt das Ministerium den Stapelmodus. Ein Paket mit 100 Rechnungen nutzt die verfügbare Kapazität normalerweise effizienter als 100 interaktive Übermittlungen. Das Hochladen von Paketteilen innerhalb einer offenen Stapelsitzung zählt nicht zu den API-Anfragelimits und darf parallel erfolgen. Das Öffnen und Schließen der Stapelsitzung bleibt jedoch begrenzt.

Dasselbe Prinzip gilt für den Abruf. Laut KSeF sollten Systeme mit hohem Datenvolumen asynchrone Rechnungsexporte verwenden und die Daten mit einer lokalen Datenbank synchronisieren. Wenn Sie KSeF jedes Mal aufrufen, sobald jemand eine Rechnung öffnet, behandeln Sie den zentralen Rechnungsspeicher wie eine Anwendungsdatenbank und verschwenden das knappe Download-Kontingent.

Was sollten Sie im Produktivbetrieb überwachen?

Überwachen Sie die Kontingentnutzung, Wiederholungsentscheidungen, asynchronen Ergebnisse und den Wiederherstellungsstatus, ohne Rechnungsinhalte oder Zugangsdaten zu protokollieren. Die Zahl der 429-Antworten zeigt nur, dass das System bereits zu spät reagiert, nicht warum.

Protokollieren Sie mindestens:

• die gültigen Limits und den Zeitpunkt ihrer letzten Aktualisierung;
• die Zahl der Anfragen nach Umgebung, Kontext, ausgehender IP-Adresse und Limitgruppe;
• die Zahl der 429-Antworten, den Wert Retry-After, die Versuchsnummer und das Endergebnis;
• Länge und Alter der Warteschlangen für Übermittlungen, Statusabfragen, Exporte und Downloads;
• die Zeit von der Übermittlung bis zu einem Endstatus der Rechnung;
• die Zahl der ausstehenden Vorgänge mit Status 100/150, der Duplikate mit 440 und der abgebrochenen Vorgänge mit 550;
• Schreibvorgänge mit unbekanntem Ausgang, die auf einen Abgleich warten;
• den Zustand des Circuit Breakers und die Zahl der abgewiesenen Aufrufe;
• die Sitzungs-, Rechnungs-, Export- und lokalen Versuchsreferenzen, die der Support benötigt.

Sensible Felder gehören weder in Protokolle noch in Fehlertracking-Systeme. Rechnungs-XML, Käuferdaten, Authentifizierungs-Token, UPO-Dokumente, Cookies und rohe Anfrageparameter dürfen nicht Teil eines Fehlerereignisses sein. Kennungen, Zustandsübergänge, Antwortklasse, Trace-ID und Laufzeiten reichen normalerweise aus, um Fehler bei Wiederholungen zu diagnostizieren.

Lösen Sie Warnungen anhand von Trends aus, nicht nur bei einzelnen Antworten. Eine absehbar steigende Auslastung des Stundenkontingents, eine wachsende Statuswarteschlange oder wiederholt hohe Retry-After-Werte geben Ihnen Zeit, die vorgelagerten Systeme zu drosseln, bevor die Integration in eine Wiederholungsspirale gerät.

Wie behandelt KSeF Kit Wiederholungen derzeit?

KSeF Kit nutzt dauerhafte Übermittlungsversuche und gespeicherte KSeF-Referenzen. So lassen sich Statusabfragen fortsetzen, ohne dieselbe Rechnung blind erneut zu übermitteln. Die öffentliche Dokumentation beschreibt fünf Wiederholungsversuche mit steigenden Wartezeiten bei vorübergehenden Fehlern mit 429, 500 und 550.

Der Ablauf einer Einreichung beginnt mit einer finalisierten Stripe-Rechnung als unveränderlicher Quelle. KSeF Kit wandelt sie in FA(3) um, öffnet eine Online-Sitzung, übermittelt sie und fragt anschließend KSeF-Nummer und UPO ab. Jeder Übermittlungsversuch ist ein separater Datensatz. Wird die Statusabfrage unterbrochen, kann ein späterer Job den bereits angenommenen Vorgang anhand der gespeicherten Referenzen fortsetzen.

Der KSeF-API-Leitfaden und das Betriebshandbuch für Ausfälle unterscheiden zwischen vorübergehenden Wiederholungen und dem Abgleich. Die für Nutzer sichtbaren Status trennen wartende, in Übermittlung befindliche, angenommene, abgelehnte und blockierte Vorgänge. Laut der Sicherheitsdokumentation enthalten gehostete Fehler in Sentry Kennungen und Zustände, schließen Rechnungsinhalte, personenbezogene Käuferdaten, Token, UPOs, Anfrageparameter und Cookies jedoch aus.

Das sind die aktuellen Produktgrenzen. KSeF Kit führt öffentlich weder Anfragebudgets pro Kontext noch eine dokumentierte Strategie für Zufallsverzögerungen, Dashboards für API-Limits oder die Ausstellung im Offline24-Verfahren als Produktfunktionen auf. Die umfassendere Architektur aus diesem Leitfaden beschreibt den Standard, auf den eine produktive Integration hinarbeiten sollte, keine Liste verborgener Produktfunktionen.

Die Betriebsregel ist einfach: Drosseln Sie Anfragen, bevor KSeF Sie stoppen muss, halten Sie sich an die vorgegebene Wartezeit und verwechseln Sie das Wiederholen einer Übertragung nie mit der Entscheidung, ob eine Rechnung bereits existiert.