Errors
Errors return a JSON body with a machine-readable type, a human-readable message, and a request_id to quote to 1key support.
{
"error": {
"type": "insufficient_scope",
"message": "This key needs hubs:command.",
"request_id": "req_5LqW2v"
}
}
Branch on type, not on message: messages may change, types do not.
| Status | type |
Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_request |
Malformed JSON, unknown action, bad parameter | No: fix the request |
| 401 | unauthenticated |
Missing, malformed, revoked or unknown key | No: check the key |
| 403 | insufficient_scope |
The key lacks a scope; the message names it | No: use a key with the scope |
| 403 | forbidden |
An API key tried to change or remove an owner, or make one | No: an owner does it in the portal |
| 404 | not_found |
No such site, hub or device in your organization | No |
| 409 | idempotency_conflict |
Idempotency-Key reused with a different body |
No: use a new key |
| 410 | cursor_expired |
Event cursor older than 24 hours, or from before a hub reset | No: resync |
| 422 | command_refused |
The hub won't drive that device, for example a lock that did not join securely | No |
| 422 | hub_not_addable |
The Serial is unknown, the hub has not come online, or another organization has it | Yes, once the hub is online |
| 429 | rate_limited |
Too many requests | Yes, after Retry-After seconds |
| 500 | internal_error |
A 1key fault | Yes, with backoff |
| 502 | hub_error |
The hub failed, or the request could not be sent to it | Yes, with backoff |
| 503 | hub_offline |
The hub is not connected | Yes, later; watch for hub.connected |
| 503 | hub_unavailable |
The hub is connected but can't do it now | Yes, with backoff |
| 504 | hub_timeout |
The hub did not answer in time | Yes, with backoff |
Hubs you do not own
A hub that exists but belongs to another organization returns 404, exactly like a hub that does not exist. The API never reveals other organizations' hubs.
Failed commands
A command can be accepted (202) and still not happen: the device may not respond, or may report something else. That is not an HTTP error. The channel's status becomes failed or diverged; see commands.