Taktsperre
Die API begrenzt, wie viele Anfragen in einer Minute durchgehen. Wer darüber liegt, bekommt 429 und muss warten.
Die Grenzen
| Bereich | Grenze |
|---|---|
alles Übrige – auch /api/worktime/v1 und /api/lexware/v1 | 300 Anfragen je Minute |
POST /api/v1/auth/login und der Schritt mit dem Zwei-Faktor-Code | je 10 je Minute |
POST /api/v1/auth/register | 5 je Minute |
POST /api/v1/auth/passwort-vergessen | 3 je fünf Minuten |
POST /api/v1/auth/passwort-zuruecksetzen | 5 je fünf Minuten |
| Einladung ansehen / annehmen | 20 bzw. 5 je Minute |
| Kundenportal (öffentlich) | 60 je Minute, Antworten und Bezahlen 10 je Minute |
POST /api/v1/kombi/status | 3000 je Minute |
Anmeldung, Registrierung und Passwort sind eng getaktet, weil sie öffentlich sind und ein Geheimnis prüfen oder eine Mail verschicken – genau das, was ein Angreifer in Schleife probieren würde. Die Kombi-Abfrage dagegen ist großzügig: Dort fragt der Cloud-Server von WorkTime Pro in seinem täglichen Lauf nach jedem verbundenen Betrieb, von einer einzigen Adresse; Fremde hält dort die Signatur draußen, nicht die Grenze.
Wonach gezählt wird
Mit API-Schlüssel zählt der Schlüssel, sonst die Adresse.
WorkTime Pro in der Cloud spricht für viele Betriebe von derselben Adresse. Würde nach Adresse gezählt, bremsten sich diese Betriebe gegenseitig aus – der Abgleich des einen ließe die Rechnungen des anderen warten. Ein Schlüssel gehört genau einem Betrieb, also bekommt jeder Schlüssel sein eigenes Kontingent. Zwei Schlüssel teilen sich nichts.
Ohne Schlüssel – also auch für die angemeldete Oberfläche – zählt die IP-Adresse. Alle Arbeitsplätze hinter demselben Anschluss teilen sich damit die 300 Anfragen je Minute.
Gezählt wird im Speicher des API-Prozesses; ein Neustart setzt die Zähler zurück.
Hinter Caddy
Vor der API stehen Caddy und die Oberfläche. Die echte Adresse des Aufrufers steht deshalb in X-Forwarded-For, und die API glaubt diesem Kopf nur, wenn er von einem Weiterleiter aus dem eigenen Netz kommt (lokal, Docker, LAN). Ein Kopf, den jemand von außen selbst mitschickt, zählt nicht – sonst könnte sich jeder mit einer erfundenen Adresse ein frisches Kontingent holen. Caddy setzt den Kopf von selbst (siehe HTTPS mit Caddy).
Die Antwort bei 429
Jede Antwort trägt die Kopfzeilen X-RateLimit-Limit, X-RateLimit-Remaining und X-RateLimit-Reset – ein Programm sieht also vorher, wie viel noch geht. Ist die Grenze erreicht, kommt dazu Retry-After mit der Wartezeit in Sekunden.
Der Leib hängt von der Schnittstelle ab:
| Schnittstelle | Leib |
|---|---|
/api/v1 | { "statusCode": 429, "message": "ThrottlerException: Too Many Requests", … } |
/api/worktime/v1 | { "fehler": "zu_viele", "meldung": "Zu viele Anfragen – bitte nach der Wartezeit (Retry-After) erneut versuchen." } |
/api/lexware/v1 | Fehlerformat von Lexware mit "status": 429 |
Was ein Programm tun sollte: Retry-After abwarten und dann weitermachen – nicht sofort wiederholen. Jede Anfrage während der Sperre zählt mit. Wer viele Datensätze abgleicht, verteilt die Anfragen besser über die Minute, als sie auf einmal abzufeuern; die WorkTime-Schnittstelle liefert dafür Seiten mit bis zu 250 Einträgen.
Was außerdem gegen das Durchprobieren wirkt
Nach fünf fehlgeschlagenen Anmeldungen wird das Konto für fünfzehn Minuten gesperrt – unabhängig von der Taktsperre und davon, von welcher Adresse die Versuche kamen. Die Meldung nennt die Uhrzeit, ab der es wieder geht.