Limits and error codes

All limits and status codes in one place, with what your device should do for each code. Follow them and you won't lose readings, and your device stays online in the portal.

Limits#

What	Limit	Counted per
All requests with a token	60 per minute	token
Of which uploads to /device/readings	10 per minute	token
All requests to config, readings and status	600 per minute	IP address, also with a bad token
hello	10 per minute	uuid
hello	30 per minute	IP address; an IPv6 /64 network counts as one address

Two devices behind the same router each have their own 60 per minute. They only share the 600 per IP address.

Per batch or reading	Limit
Readings per batch	1000, on at most 7 calendar days (UTC)
Unknown sensor codes	16 different ones per batch, and 25,000 quarantined readings per device per day
measured_at	At most 5 minutes in the future and 365 days back
value	No greater than 10⁹ in absolute terms

Status codes#

Code	Meaning	What to do
200	Done. For readings also when individual readings were rejected	Read the answer per reading
204	Status stored	Nothing
304	Configuration unchanged	Keep your current configuration
401	The token is not (or no longer) valid	See below
422	The request is not valid as a whole	Don't resend: look for the bug
429	Too many requests	Wait at least as many seconds as Retry-After says, then send the same request again
5xx	The server has a problem or is in maintenance (503)	Try again later: see below

401: the token is not valid#

You get 401 when:

• the Authorization header is missing or does not contain a token in the right form;
• the token is unknown or the secret is wrong;
• a new key was made, in the portal or by pairing with a code;
• the key was switched off, for example because the device was deleted, or the device was set to inactive;
• the prefix does not match the device: bb_live_ for a simulated device, or bb_test_ for a real one.

The answer is {"message": "Unauthenticated."} with the header WWW-Authenticate: Bearer. Stop sending, but keep your buffer and try again at a slow pace, for example every 15 minutes. With a new token everything can still go through.

422: the request is not valid#

The answer has a message and the errors per field in errors. Those texts are meant for people: write them to your log, but don't build logic on them.

5xx and network errors#

Keep your batch and wait longer each time: for example 5 seconds, then double that, up to at most 15 minutes. Add some randomness, so that not every device comes back in the same second after an outage. If there is a Retry-After, wait at least that long.

Other codes#

A 403, 404, 413 or a redirect usually comes from something on the way, such as a proxy, a firewall or a wrong URL. Keep your readings and fix the problem. Don't follow redirects: they could send your token to another server.

Heartbeat and offline#

With POST /device/status your device says it is there. All fields are optional:

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

Field	Rule
firmware_version	Up to 32 characters
uptime_s	Seconds since startup, 0 or more
ip	A valid IPv4 or IPv6 address
rssi	Signal strength in dBm, from -120 to 0
buffered	Readings still waiting in the buffer
last_error	The latest error, up to 500 characters

The answer is 204 without a body. If one field is invalid, the whole status gets 422. The portal shows the firmware version under Firmware; the server stores the other fields, but the portal does not show them at the moment.

A device that makes no request with a valid token for 15 minutes shows as Offline. That is the default, and the same threshold applies to the Device offline alert. A device that never sent anything shows as Never seen. So send a status about every 5 minutes, also when there is nothing to upload, for example while no circuit has been chosen yet.

What you see in the portal#

• Last seen: every request with a valid token updates this, at most once every 30 seconds.
• API connection errors: on the device page, for whoever manages the device. Failed requests with a valid token (the same failure at most once every 10 minutes) and uploads with rejected readings or unknown codes (at most once an hour). They are kept for 90 days. A 401 does not appear here: the server does not know which device it was.

Simulated devices#

Want to test your software without putting test data into a real installation? Use a simulated device. Only BoilerBuddy can set a device to simulated: get in touch for that.

• Its token starts with bb_test_ and the portal shows it with the label Simulated.
• Its alerts appear only in the portal, never by email.
• It cannot be paired with a code.