Errors
Errors
Errors return a JSON body with a machine-readable type, a human-readable message, a request_id to quote to 1key support, and a doc_url that explains the error.
{
"error": {
"type": "insufficient_scope",
"message": "This key needs hubs:command.",
"request_id": "req_5LqW2v",
"doc_url": "https://developers.1keyplatform.dev/docs/authentication#scopes"
}
}
Branch on type, not on message: messages may change, types do not.
The portal's request log shows your keys' requests from the last 30 minutes, with their responses. Search it by request_id.
| 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 |
The key's creator isn't an owner or admin, for what only they may do: reset a hub's cloud link or device network, change its Wi-Fi, list pending invitations. Or a key tried to change or remove an owner, or make one | No: use a key an owner or admin created, or 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 |
| 409 | idempotency_conflict |
A request with this Idempotency-Key is still running |
Yes, shortly, with the same key |
| 409 | conflict |
An automation's revision doesn't match: someone changed it since. See revisions |
No: read it again |
| 409 | conflict |
A newer command to the same lock or garage door replaced this one before it went out | No: the newer command stands |
| 409 | conflict |
The key to rotate, or a key above it, is revoked. See rotating keys | No: rotate with a key that works |
| 409 | device_responding |
A forced removal pinged the device and it answered. See force removal | No: exclude it, or power it off first |
| 409 | unlock_expired |
The intercom got a door unlock after it expired, 10 seconds after it was sent; the door did not open. See intercoms | Yes, with a new unlock |
| 409 | slots_full |
Every slot on the lock holds a credential. See access | No: revoke one first |
| 410 | cursor_expired |
Event cursor older than the 30 days events are kept | No: resync |
| 413 | invalid_request |
The body is over 4 MB | No: send less in one request |
| 422 | command_refused |
The hub won't drive that device, for example a lock that did not join securely | No |
| 422 | automation_rejected |
The hub refused an automation or a schedule; error.problems lists why. See automations |
No: fix the automation |
| 422 | hub_not_addable |
The Serial isn't one 1Key made, or another organization has it | No |
| 422 | intercom_not_addable |
The Serial isn't one 1Key made, or another organization has it | No |
| 422 | face_rejected |
A face's photo isn't good enough to learn it from; photos says which and why |
With other photos |
| 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.online |
| 503 | hub_unavailable |
The hub is connected but can't do it now | Yes, with backoff |
| 503 | hub_unavailable |
"this firmware cannot read the site's database": the hub runs older firmware than the one that wrote its data, and its health lists DomainUnavailable. It refuses every request until its firmware is updated |
No |
| 503 | face_unavailable |
Faces can't be learned from photos right 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.