1KEY Developers
Guides

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.

json
{
  "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.