Errors

Stable codes to branch on, and what each one means.

Failures return a JSON body with a human error and a stable code. Branch on the code, not the message — messages get reworded.

403

{
  "error": "This key is missing the 'devices:control' scope.",
  "code": "insufficient_scope",
  "required": "devices:control",
  "granted": ["devices:read", "telemetry:read"]
}

Status	Code	Meaning
400	invalid_body	The request body was missing or not a JSON object.
400	invalid_query	A query parameter was malformed — usually a bad `since` timestamp.
401	key_invalid	No key was sent, or it is not a key we issued.
401	key_expired	The key passed its expiry date. Create a new one.
401	key_revoked	The key was revoked in the console.
401	key_blocked	The account that owns the key is disabled.
403	insufficient_scope	Valid key, but it lacks the scope this endpoint needs. The response lists both required and granted.
403	origin_not_allowed	Called from a browser on an origin the key does not permit.
403	device_not_owned	An automation named a device that is not in this account — checked on the trigger as well as the actions.
404	not_found	No such device, scene or endpoint — or it belongs to another account.
429	rate_limited	More than 600 requests in a minute for this key.

A device that belongs to another account returns 404, not 403. That is deliberate: a 403 would confirm the id exists.

Errors

Stable codes to branch on, and what each one means.

Failures return a JSON body with a human error and a stable code. Branch on the code, not the message — messages get reworded.

403

{
  "error": "This key is missing the 'devices:control' scope.",
  "code": "insufficient_scope",
  "required": "devices:control",
  "granted": ["devices:read", "telemetry:read"]
}

Status	Code	Meaning
400	invalid_body	The request body was missing or not a JSON object.
400	invalid_query	A query parameter was malformed — usually a bad `since` timestamp.
401	key_invalid	No key was sent, or it is not a key we issued.
401	key_expired	The key passed its expiry date. Create a new one.
401	key_revoked	The key was revoked in the console.
401	key_blocked	The account that owns the key is disabled.
403	insufficient_scope	Valid key, but it lacks the scope this endpoint needs. The response lists both required and granted.
403	origin_not_allowed	Called from a browser on an origin the key does not permit.
403	device_not_owned	An automation named a device that is not in this account — checked on the trigger as well as the actions.
404	not_found	No such device, scene or endpoint — or it belongs to another account.
429	rate_limited	More than 600 requests in a minute for this key.

A device that belongs to another account returns 404, not 403. That is deliberate: a 403 would confirm the id exists.