API Rate Limits DE

API-Rate-Limits

Sprache: Deutsch · English

Die Husqvarna-APIs (Gardena Smart System und Automower Connect) haben ein monatliches Anfragekontingent von ungefähr 10.000 Anfragen pro Monat und Application. Diese Seite beschreibt, wie die Integration innerhalb dieser Grenzen bleibt und was passiert, wenn sie überschritten werden.

Jede API hat ihr eigenes unabhängiges Budget. Die Nutzung der einen API beeinflusst die andere nicht. Beide APIs verwenden denselben OAuth-Token-Endpunkt, aber Token-Anfragen werden nicht auf das jeweilige API-Kontingent angerechnet.

Datenaktualisierung — Architektur

Beide APIs verwenden dieselbe Architektur: WebSocket-Push in Echtzeit mit REST-Polling als Fallback. Jede API unterhält eine eigene Verbindung.

Gardena Smart System API

Startup (bei jedem HA-Neustart oder Integrations-Reload):

#	API-Aufruf	Zweck
1	POST /oauth2/token	OAuth2-Access-Token holen
2	GET /locations/{id}	Alle Geräte und ihren aktuellen Zustand abrufen
3	POST /websocket	WebSocket-URL für Echtzeit-Updates anfordern
4	WebSocket-Connect	Persistente Verbindung für Push-Updates öffnen

Macht pro Startup 3 REST-Aufrufe + 1 WebSocket-Verbindung.

Normalbetrieb (WebSocket verbunden):

API-Aufruf	Häufigkeit	Zweck
GET /locations/{id}	alle 60 Minuten	Health-Check-Poll — prüft Geräteliste, erkennt neue Geräte
POST /oauth2/token	alle ~55 Minuten	Token-Refresh (separater Endpunkt, zählt nicht aufs Kontingent)
WebSocket-Nachrichten	kontinuierlich (Push)	Alle Gerätezustands-Updates kommen hier ohne REST-Kosten an

Tagesumsatz: ~24 Health-Check-Polls/Tag — etwa 7 % des Monatsbudgets.

Fallback-Betrieb (WebSocket ausgefallen):

API-Aufruf	Häufigkeit	Zweck
GET /locations/{id}	alle 5 Minuten	Polling auf Gerätezustand (entspricht der Update-Frequenz der Gardena-Sensor-Hardware)
POST /oauth2/token	alle ~55 Minuten	Token-Refresh

Tagesumsatz: ~288 Polls/Tag — etwa 86 % des Monatsbudgets.

Automower Connect API

Startup:

#	API-Aufruf	Zweck
1	POST /oauth2/token	OAuth2-Access-Token holen (geteilte Auth)
2	GET /mowers	Alle Mäher und ihren aktuellen Zustand abrufen
3	WebSocket-Connect	Persistente Verbindung für Push-Updates öffnen

Normalbetrieb (WebSocket verbunden):

API-Aufruf	Häufigkeit	Zweck
GET /mowers	alle 60 Minuten	Health-Check-Poll
POST /oauth2/token	alle ~55 Minuten	Token-Refresh
WebSocket-Nachrichten	kontinuierlich (Push)	Alle Mäher-Zustands-Updates

Tagesumsatz: ~24 Polls/Tag — etwa 7 % des Monatsbudgets.

Fallback-Betrieb (WebSocket ausgefallen):

API-Aufruf	Häufigkeit	Zweck
GET /mowers	alle 5 Minuten	Polling auf Mäher-Zustand
POST /oauth2/token	alle ~55 Minuten	Token-Refresh

Tagesumsatz: ~288 Polls/Tag — etwa 86 % des Monatsbudgets.

Benutzerausgelöste Befehle

API-Aufruf	Drosselung	Zweck
PUT /command/{id} (Gardena)	Token-Bucket — 10 Token, Refill 1 / 5 s	Ventil-, Schalter-, Mäher-Befehle
POST /mowers/{id}/actions (Automower)	Token-Bucket — 10 Token, Refill 1 / 5 s	Mäher-Aktionen (Start, Pause, Park)
PATCH /mowers/{id}/settings (Automower)	Token-Bucket — 10 Token, Refill 1 / 5 s	Schnitthöhe, Scheinwerfer, Sperrzonen

Jeder Tastendruck oder jede Automatisierungsaktion ist ein API-Aufruf. Der Token-Bucket erlaubt kleine Bursts (z. B. mehrere Ventile nacheinander öffnen) und begrenzt die Dauerrate auf ≤1 Befehl / 5 s.

Wie die Integration im Limit bleibt

Strategie	Details
WebSocket-First-Architektur	Zustands-Updates kommen in Echtzeit über persistente WebSockets. REST-Polling ist nur Fallback. Die äussere Reconnect-Schleife versucht 3 Mal über ~20 Minuten neu zu verbinden (60 s → 5 min → 15 min) und holt dabei jeweils eine frische signierte WS-URL. Ein Watchdog-Timer prüft alle 60 s, ob die WebSocket noch Daten empfängt — bleibt sie 5 Minuten still, wird die Verbindung zwangsweise erneuert.
Single-Use-WebSocket-URLs	Die signierten WS-URLs von Husqvarna sind nur einmal nutzbar — wird eine URL abgelehnt (z. B. HTTP 410), bringt ein erneuter Versuch mit derselben URL nichts. Fehler werden sofort an den Coordinator eskaliert, statt Bandbreite an einer toten URL zu verbrennen. Bei jedem neuen Connect wird eine frische URL geholt.
WebSocket-URL-Caching	Innerhalb eines Connect-Versuchs wird die frisch geholte URL gecacht und solange wiederverwendet, wie der Auth-Token gültig ist. Der Cache wird ungültig, wenn der Token abläuft oder ein Connect-Versuch scheitert.
Connect-Guard	Ein Async-Lock verhindert parallele WebSocket-Connect-Versuche (z. B. wenn Watchdog und Poll-Zyklus gleichzeitig anlaufen) und vermeidet so doppelte API-Aufrufe.
Circuit Breaker	Nach 3 aufeinanderfolgenden WebSocket-Start-Fehlern aktiviert die Integration eine 15-Minuten-Cooldown, in der kein neuer WebSocket-Verbindungsversuch stattfindet (REST-Polling läuft weiter). Cooldown eskaliert auf 30 min nach 5 Fehlern und 60 min nach 7+. Eine erfolgreiche Verbindung setzt den Zähler zurück. Auth-Fehler umgehen den Circuit Breaker und lösen stattdessen Reauth aus.
WS-Handshake-Kill-Switch	Nach wiederholten 4xx-Handshake-Ablehnungen (z. B. HTTP 410/403/429 — typisch für eine serverseitig gesperrte Application) wird das WebSocket-Subsystem für 1 Stunde ausgesetzt und auch das REST-Polling pausiert, bis ein echtes Geräte-Update bestätigt, dass der Stream wieder gesund ist. Verhindert, dass Konto-Sperren ~288 REST-Aufrufe/Tag verbrennen. Eine Repair-Issue (husqvarna_application_blocked) weist den Nutzer darauf hin, die Husqvarna-Application zu rotieren. Der Kill-Switch-Zustand wird auf Disk persistiert (seit 1.12.8) und überlebt damit HA-Neustarts und Setup-Retries des Config-Entries — der vorherige reine In-Memory-Zähler wurde bei jedem Retry zurückgesetzt, wodurch die Integration in einer 5-Minuten-Schleife aus „Fehler → frischer Coordinator → Fehler" hängenblieb und immer wieder Quota verbrannte, um denselben Block zu bestätigen.
Persistenter Application-Block-Detektor	Wenn die Rate-Limit-Leiter ≥10-mal feuert UND in den letzten 24 Stunden kein erfolgreicher Poll stattgefunden hat (oder mit der aktuellen Application noch nie einer), wird dieselbe husqvarna_application_blocked-Repair-Issue ausgelöst — auch ohne WebSocket-Handshake-Denial. Symptom einer serverseitigen Sperre, bei der REST und WS beide weiterhin 429/410 liefern; das einzige Mittel ist, die Application zu rotieren. Die Issue verschwindet automatisch nach mehreren aufeinanderfolgenden erfolgreichen Polls.
WS-Sitzungs-Timer (seit v2.0.5)	Husqvarna erzwingt serverseitig ein 2-Stunden-Maximum für WebSocket-Sitzungen zum Lastausgleich. Wenn der Server nach 2 Stunden einen regulären CLOSE-Frame sendet, beendet die Bibliothek die Empfangsschleife normal (kein Fehler), sodass _ws_connected still auf True geblieben wäre. Ein One-Shot-Timer (WS_MAX_SESSION_SECONDS = 6900 s, 1 Std. 55 Min.) wird jetzt bei jedem Sitzungsaufbau gesetzt. Bei Ablauf trennt _async_ws_session_expired() die Verbindung proaktiv und plant einen normalen Reconnect — kein Datenloch, kein veralteter Zustand. Der Timer wird bei explizitem Fehler oder Shutdown abgebrochen.
Adaptives Polling-Intervall	Bei verbundener WebSocket: nur 60-Minuten-Health-Check. Bei abgebrochener WebSocket: 5-Minuten-Polling (entspricht der Update-Rate der Sensor-Hardware).
Graduierter Rate-Limit-Backoff	Liefert ein API-Aufruf HTTP 429 — auch Token-Refresh oder WS-URL-Anfragen — backt das Polling exponentiell zurück (5 min → 10 → 20 → 40 → 60 min max) und setzt sich erst nach mehreren aufeinanderfolgenden erfolgreichen Antworten zurück.
Command-Throttling (Token-Bucket)	10 Token, Refill 1 Token pro 5 s. Erlaubt kleine Bursts und begrenzt die Dauerrate auf ≤1 Befehl / 5 s.
Auto-Stop als Sicherheitsnetz	Sinkt das monatliche API-Budget unter 5 % Restwert (weniger als 500 von 10 000 Anfragen), pausiert der Coordinator REST-Polls, WebSocket-(Re)Connect-Versuche und Befehle des Benutzers — letztere geben eine übersetzte Fehlermeldung zurück (api_budget_exhausted). Der Normalbetrieb wird zu Beginn des nächsten Kalendermonats automatisch wieder aufgenommen, oder früher, wenn eine neue Husqvarna-Application angelegt wird.
Unabhängige Budgets	Beide APIs haben jeweils ~10 000 Anfragen/Monat. Die Nutzung der einen beeinflusst die andere nicht.

Tipps zur Vermeidung von Rate-Limits

• Home Assistant nicht häufig neu starten. Jeder Neustart löst einen vollständigen API-Poll und einen neuen WebSocket-Verbindungsaufbau aus.
• Schnellfeuer-Automatisierungen vermeiden. Bei Automatisierungen, die in einer Schleife mehrere Befehle senden, Verzögerungen einbauen. Die Integration setzt mindestens 5 Sekunden durch, längere Pausen sind aber besser für das Kontingent.
• Eigenen API-Key für Home Assistant verwenden. Die Budget-Sensoren gehen davon aus, dass die vollen 10 000 Anfragen/Monat exklusiv für diese Integration zur Verfügung stehen. Werden dieselben Husqvarna-Application-Zugangsdaten von einer anderen Smart-Home-Plattform mitgenutzt, wird die Prozentanzeige ungenau. Pro System eine separate Application im Husqvarna Developer Portal anlegen.
• Eine Integrationsinstanz pro API. Jede zusätzliche Instanz erzeugt eigenes Polling- und WebSocket-Aufkommen.
• Auf Rate-Limit-Warnungen achten. In den Home-Assistant-Logs nach Meldungen mit "Rate limited" suchen. Der Hub-Diagnose-Sensor Verbleibendes API-Budget eignet sich auch gut als Trigger für Warn-Automatisierungen.

Verhalten bei Rate-Limit

1. Die Integration loggt eine Warnung (z. B. Rate limited by Gardena API (hit #1), backing off to 0:05:00).
2. Das Polling-Intervall steigt im graduierten Backoff: 5 min → 10 min → 20 min → 40 min → 60 min (max).
3. Bestehende Entity-Zustände bleiben verfügbar (gecacht aus dem letzten erfolgreichen Update und WebSocket-Nachrichten).
4. Befehle können bis zum Rate-Limit-Reset fehlschlagen.
5. Nach mehreren aufeinanderfolgenden erfolgreichen API-Antworten setzt sich der Backoff-Zähler zurück und das normale Polling-Intervall wird wiederhergestellt.
6. Ist das Monatsbudget fast aufgebraucht (< 5 % Restwert), übernimmt das Auto-Stop-Sicherheitsnetz: Polls, WS-Reconnects und Befehle werden bis zum Monatswechsel verweigert.

---

Siehe auch: Fehlerbehebung