Limieten en foutcodes

Alle limieten en statuscodes op een rij, met wat je apparaat bij elke code doet. Zo raak je geen metingen kwijt en blijft je apparaat in het portaal online.

Limieten#

Wat	Limiet	Geteld per
Alle verzoeken met een token	60 per minuut	token
Daarvan uploads naar /device/readings	10 per minuut	token
Alle verzoeken naar config, readings en status	600 per minuut	IP-adres, ook met een fout token
hello	10 per minuut	uuid
hello	30 per minuut	IP-adres; een IPv6-/64-netwerk telt als één adres

Twee apparaten achter dezelfde router hebben elk hun eigen 60 per minuut. Alleen de 600 per IP-adres delen ze.

Per batch of meting	Limiet
Metingen per batch	1000, op hooguit 7 kalenderdagen (UTC)
Onbekende sensorcodes	16 verschillende per batch, en 25 000 metingen in quarantaine per apparaat per dag
measured_at	Hooguit 5 minuten in de toekomst en 365 dagen terug
value	Absoluut niet groter dan 10⁹

Statuscodes#

Code	Betekenis	Wat je doet
200	Gelukt. Bij readings ook als er losse metingen zijn afgewezen	Lees het antwoord per meting
204	Status opgeslagen	Niets
304	Configuratie niet veranderd	Houd je huidige configuratie
401	Het token klopt niet (meer)	Zie hieronder
422	Het verzoek klopt als geheel niet	Niet opnieuw sturen: zoek de fout
429	Te veel verzoeken	Wacht minstens zo veel seconden als Retry-After zegt en stuur hetzelfde verzoek opnieuw
5xx	De server heeft een probleem of is in onderhoud (503)	Later opnieuw: zie hieronder

401: het token klopt niet#

Je krijgt 401 als:

• de Authorization-header ontbreekt of geen token in de juiste vorm bevat;
• het token onbekend is of het geheim niet klopt;
• er een nieuwe sleutel is gemaakt, in het portaal of door te koppelen met een code;
• de sleutel is uitgezet, bijvoorbeeld omdat het apparaat is verwijderd, of het apparaat inactief is gezet;
• het voorvoegsel niet bij het apparaat past: bb_live_ voor een gesimuleerd apparaat, of bb_test_ voor een echt.

Het antwoord is {"message": "Unauthenticated."} met de header WWW-Authenticate: Bearer. Stop met versturen, maar houd je buffer en probeer het rustig opnieuw, bijvoorbeeld eens per kwartier. Met een nieuw token gaat alles alsnog mee.

422: het verzoek klopt niet#

Het antwoord heeft een message en per veld de fouten in errors. Die teksten zijn voor mensen: zet ze in je log, maar bouw er geen logica op.

5xx en netwerkfouten#

Houd je batch en wacht steeds langer: bijvoorbeeld 5 seconden, dan het dubbele, tot hooguit 15 minuten. Voeg wat toeval toe, zodat na een storing niet alle apparaten in dezelfde seconde terugkomen. Staat er een Retry-After bij, wacht dan minstens zo lang.

Andere codes#

Een 403, 404, 413 of een redirect komt meestal van iets onderweg, zoals een proxy, een firewall of een verkeerde URL. Houd je metingen en los het op. Volg geen redirects: die kunnen je token naar een andere server sturen.

Heartbeat en offline#

Met POST /device/status laat je apparaat weten dat het er is. Alle velden zijn optioneel:

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

Veld	Regel
firmware_version	Tot 32 tekens
uptime_s	Seconden sinds het opstarten, 0 of meer
ip	Een geldig IPv4- of IPv6-adres
rssi	Signaalsterkte in dBm, van -120 tot 0
buffered	Metingen die nog in de buffer staan
last_error	De laatste fout, tot 500 tekens

Het antwoord is 204 zonder body. Klopt één veld niet, dan krijgt de hele status 422. Het portaal toont de firmwareversie bij Firmware; de andere velden bewaart de server, maar toont het portaal nu niet.

Stuurt een apparaat 15 minuten lang geen enkel verzoek met een geldig token, dan staat het op Offline. Dat is de standaard, en dezelfde grens geldt voor de melding Apparaat offline. Een apparaat dat nog nooit iets stuurde, staat op Nog nooit gezien. Stuur daarom ongeveer elke 5 minuten een status, ook als er niets te versturen is, bijvoorbeeld zolang er nog geen regelkring is gekozen.

Wat je in het portaal ziet#

• Laatst gezien: elk verzoek met een geldig token werkt dit bij, hooguit eens per 30 seconden.
• Fouten in de API-koppeling: op de pagina van het apparaat, voor wie het beheert. Mislukte verzoeken met een geldig token (dezelfde fout hooguit eens per 10 minuten) en uploads met afgewezen metingen of onbekende codes (hooguit eens per uur). Ze blijven 90 dagen staan. Een 401 staat er niet bij: de server weet dan niet om welk apparaat het gaat.

Gesimuleerde apparaten#

Wil je je software testen zonder testdata in een echte installatie? Gebruik dan een gesimuleerd apparaat. Alleen BoilerBuddy kan een apparaat op gesimuleerd zetten: neem daarvoor contact op.

• Het token begint met bb_test_ en het portaal toont het label Gesimuleerd.
• Meldingen zie je alleen in het portaal, nooit per e-mail.
• Koppelen met een code kan niet.