A failed response of a route under /v1 or /device/v1 has one JSON form, so an app reads the code and the HTTP status and ignores the rest of the text. The routes /healthz and /readyz have a small status body of their own, and they answer 503 when the service is not healthy. A proxy in front of the API can answer with another body or none, so an app checks the HTTP status first.
{
"code": "email_taken",
"message": "The email has an account"
}The message is English text for a developer and can be reworded, so an app branches on code and on the status and never on the message. Some answers add a field.
fieldsnames each field that failed validation, with one code for each field. The codes arerequired,invalid,too_long,too_short,too_common,out_of_range,empty,end_before_start,in_the_futureandtoo_old.retryAfterSecondsis on every 429 answer and on the 503 answerbusy, and the same number is in theRetry-Afterheader.expectedSeqis on the answersequence_gapand holds the sequence number that the service wants next.pairingIdis on the answerpairing_runningand holds the id of the search that already runs. It can be left out, for example when that search ended in the meantime.
An error that the service did not plan is answered as a plain 500 with the code internal and no detail. The routes that are listed in openapi.yaml name the codes that each of them can answer.
The codes unauthorized, csrf_header_missing and origin_not_allowed apply to the routes under /v1 only, because the device routes under /device/v1 take no session and no CSRF header.
| Code | Status | Meaning | What the app does |
|---|---|---|---|
unauthorized |
401 | The request has no session, or the session ended | Send the person to sign in |
csrf_header_missing |
403 | A request that changes data has no X-Requested-With: aethera header, or the value is another one |
Send that header on every request of the app |
origin_not_allowed |
403 | The Origin header is not the origin of the app |
A deployment setting, so tell the owner of the deployment |
not_found |
404 | The id does not exist or belongs to another business, and the two cannot be told apart. A path with no route gives the same answer | Show that the item is gone |
method_not_allowed |
405 | The route does not take this method | A bug of the app |
request_timeout |
408 | The request took too long to arrive | Send it again |
payload_too_large |
413 | The body is over the limit of the route | Send less |
invalid_json |
400 | The body is empty, is not the JSON that the route expects or holds more than one value | A bug of the app |
validation_failed |
422 | A field is not valid, and fields says which |
Show the message of each field next to it |
bad_request |
400 or another status that the HTTP server chose | The HTTP server refused the request before a route saw it, and the code does not say more | Check the HTTP status |
rate_limited |
429 | A limit of the route was passed | Wait retryAfterSeconds and send again |
busy |
503 | The password check has no free slot, or a request under /v1 or /device/v1 ran for 10 seconds and failed. The answer comes with a short retry time. A write may have been saved just before the time ran out, so the app reads the data again before it sends a write for the second time |
Send the request again after a moment |
internal |
500 | The service failed and has logged it | Show a general failure, and send again later |
| Code | Status | Meaning | What the app does |
|---|---|---|---|
email_taken |
409 | The email already has an account. It is also the answer to a change to an email that another account uses | Ask for another email, or send the person to sign in |
invalid_credentials |
401 or 403 | The email or the password is wrong, with the same answer for both. It also answers a wrong password on the change of the email. A wrong password on the delete of the account answers 403, because the session is still valid | Show one sign in error |
email_not_verified |
403 | The password is right but the email is not verified yet | Offer to send the verification mail again |
token_invalid_or_expired |
410 | The link of a mail is unknown, used or expired | Ask the person to request a new mail |
resend_too_soon |
429 | A second verification or reset mail for the same address within a minute | Wait retryAfterSeconds |
already_verified |
409 | The email is verified, so it cannot be changed here | Show that the email is fixed |
A change of the email to the address that the account already has answers 422 validation_failed with the field newEmail set to invalid, after the password is checked.
| Code | Status | Meaning | What the app does |
|---|---|---|---|
claim_code_unknown |
404 | The claim code is unknown, used or expired | Ask the person to read the code from the gateway again |
too_many_gateways |
409 | The business has the most gateways that it can have | Show the limit |
gateway_claimed_elsewhere |
409 | The gateway belongs to another business | Show that the gateway belongs to another business |
key_in_use |
409 | A value that must be unique is taken already. It is the key of another gateway in most cases, and the hardware id when two claims for the same gateway ran at the same time | Send the claim again. When the key is the cause, the gateway makes a new key and enrolls again. When the same claim now answers gateway_claimed_elsewhere, the gateway belongs to another business |
no_gateway |
409 | The business has no gateway with a working key, because it has none yet or the owner cut the key of every one, so no gateway can hear a device | Send the person to claim a gateway, or to enroll the cut one again and claim its new code |
pairing_running |
409 | A search for a device is already running. The answer has pairingId, the id of that search |
Open the search with pairingId or wait for its end |
These codes are answers to the device routes under /device/v1. The firmware guide says what a gateway does for each one.
| Code | Status | Meaning |
|---|---|---|
invalid_gateway_key |
401 | The key in the bearer header is not valid, or the owner cut it off |
enrollment_expired |
410 | The claim code expired, so the gateway enrolls again |
unsupported_encoding |
415 | The body of a batch is compressed, which the service does not accept |
payload_too_large |
413 | A batch is over 256 KiB or holds more than 5000 samples |
sequence_gap |
409 | The batch skips a sequence number, and expectedSeq holds the one the service wants |
| Code | Status | Meaning | What the app does |
|---|---|---|---|
too_many_rooms |
409 | The business has the most rooms that it can have | Show the limit |
room_exists |
409 | A room with this name exists | Ask for another name |
invalid_transition |
409 | The tip is not in a state that allows this decision | Reload the tip and show its state |
no_relay |
409 | Only a plug has a relay | Hide the switch for a clamp |