Limits und Fehlercodes

Alle Limits und Statuscodes an einem Ort, mit dem, was dein Gerät bei jedem Code tun sollte. Hältst du dich daran, verlierst du keine Messwerte, und dein Gerät bleibt im Portal online.

Limits#

Was	Limit	Gezählt pro
Alle Anfragen mit Token	60 pro Minute	Token
Davon Uploads an /device/readings	10 pro Minute	Token
Alle Anfragen an config, readings und status	600 pro Minute	IP-Adresse, auch mit ungültigem Token
hello	10 pro Minute	UUID
hello	30 pro Minute	IP-Adresse; ein IPv6-/64-Netz zählt als eine Adresse

Zwei Geräte hinter demselben Router haben jeweils ihre eigenen 60 pro Minute. Sie teilen sich nur die 600 pro IP-Adresse.

Pro Stapel oder Messwert	Limit
Messwerte pro Stapel	1000, an höchstens 7 Kalendertagen (UTC)
Unbekannte Sensorcodes	16 verschiedene pro Stapel und 25.000 Messwerte in Quarantäne pro Gerät pro Tag
measured_at	Höchstens 5 Minuten in der Zukunft und 365 Tage zurück
value	Im Betrag nicht größer als 10⁹

Statuscodes#

Code	Bedeutung	Was tun
200	Erledigt. Bei readings auch, wenn einzelne Messwerte abgelehnt wurden	Lies die Antwort pro Messwert
204	Status gespeichert	Nichts
304	Konfiguration unverändert	Behalte deine aktuelle Konfiguration
401	Der Token ist nicht (mehr) gültig	Siehe unten
422	Die Anfrage ist als Ganzes ungültig	Nicht erneut senden: Such den Fehler
429	Zu viele Anfragen	Warte mindestens so viele Sekunden, wie Retry-After angibt, und sende dann dieselbe Anfrage erneut
5xx	Der Server hat ein Problem oder wird gewartet (503)	Versuch es später erneut: siehe unten

401: Der Token ist nicht gültig#

Du bekommst 401, wenn:

• der Authorization-Header fehlt oder keinen Token in der richtigen Form enthält;
• der Token unbekannt oder das Geheimnis falsch ist;
• ein neuer Schlüssel erstellt wurde, im Portal oder durch Koppeln mit einem Code;
• der Schlüssel abgeschaltet wurde, zum Beispiel weil das Gerät gelöscht wurde, oder das Gerät auf inaktiv gesetzt wurde;
• das Präfix nicht zum Gerät passt: bb_live_ für ein simuliertes Gerät oder bb_test_ für ein echtes.

Die Antwort ist {"message": "Unauthenticated."} mit dem Header WWW-Authenticate: Bearer. Hör auf zu senden, aber behalte deinen Puffer und versuch es in langsamem Tempo erneut, zum Beispiel alle 15 Minuten. Mit einem neuen Token kann noch alles durchgehen.

422: Die Anfrage ist nicht gültig#

Die Antwort hat eine message und die Fehler pro Feld in errors. Diese Texte sind für Menschen gedacht: Schreib sie in dein Log, aber bau keine Logik darauf auf.

5xx und Netzwerkfehler#

Behalte deinen Stapel und warte jedes Mal länger: zum Beispiel 5 Sekunden, dann doppelt so lange, bis höchstens 15 Minuten. Füge etwas Zufall hinzu, damit nach einem Ausfall nicht alle Geräte in derselben Sekunde zurückkommen. Gibt es ein Retry-After, warte mindestens so lange.

Andere Codes#

Ein 403, 404, 413 oder eine Weiterleitung kommt meist von etwas auf dem Weg, etwa einem Proxy, einer Firewall oder einer falschen URL. Behalte deine Messwerte und beheb das Problem. Folge keinen Weiterleitungen: Sie könnten deinen Token an einen anderen Server schicken.

Heartbeat und offline#

Mit POST /device/status sagt dein Gerät, dass es da ist. Alle Felder sind optional:

{"firmware_version": "0.3.0", "uptime_s": 3600, "ip": "192.168.1.20", "rssi": -61, "buffered": 0}

Feld	Regel
firmware_version	Bis zu 32 Zeichen
uptime_s	Sekunden seit dem Start, 0 oder mehr
ip	Eine gültige IPv4- oder IPv6-Adresse
rssi	Signalstärke in dBm, von -120 bis 0
buffered	Messwerte, die noch im Puffer warten
last_error	Der letzte Fehler, bis zu 500 Zeichen

Die Antwort ist 204 ohne Body. Ist ein Feld ungültig, bekommt der ganze Status 422. Das Portal zeigt die Firmware-Version unter Firmware; die anderen Felder speichert der Server, aber das Portal zeigt sie zurzeit nicht an.

Ein Gerät, das 15 Minuten lang keine Anfrage mit gültigem Token stellt, erscheint als Offline. Das ist der Standard, und dieselbe Schwelle gilt für die Meldung Gerät offline. Ein Gerät, das noch nie etwas gesendet hat, erscheint als Noch nie gesehen. Sende also etwa alle 5 Minuten einen Status, auch wenn es nichts hochzuladen gibt, zum Beispiel solange noch kein Regelkreis gewählt ist.

Was du im Portal siehst#

• Zuletzt gesehen: Jede Anfrage mit gültigem Token aktualisiert diesen Wert, höchstens einmal alle 30 Sekunden.
• Fehler in der API-Verbindung: auf der Seite des Geräts, für alle, die das Gerät verwalten. Fehlgeschlagene Anfragen mit gültigem Token (derselbe Fehler höchstens einmal alle 10 Minuten) und Uploads mit abgelehnten Messwerten oder unbekannten Codes (höchstens einmal pro Stunde). Sie bleiben 90 Tage erhalten. Ein 401 erscheint hier nicht: Der Server weiß nicht, welches Gerät es war.

Simulierte Geräte#

Willst du deine Software testen, ohne Testdaten in eine echte Anlage zu schreiben? Nutze ein simuliertes Gerät. Nur BoilerBuddy kann ein Gerät auf simuliert setzen: Melde dich dafür bei uns.

• Sein Token beginnt mit bb_test_, und das Portal zeigt es mit dem Label Simuliert.
• Seine Meldungen erscheinen nur im Portal, nie per E-Mail.
• Es lässt sich nicht mit einem Code koppeln.