API Errors

HTTP status codes

Code	Meaning	When you'll see it
200	Success	Successful request
400	Bad request	Malformed JSON, missing required fields
401	Unauthorized	No token, expired token, invalid token
403	Forbidden	Valid token but insufficient permissions (wrong home, view-only role)
404	Not found	Wrong endpoint URL
422	Validation error	Fields present but values invalid
500	Server error	Bug or transient failure — retry once, then report

Error response formats

REST

All REST errors return JSON with an error field:

{ "error": "Scene 'Good Night' not found in home 'My Home'" }

GraphQL

GraphQL errors appear in the errors array:

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": { "code": "AUTHENTICATION_REQUIRED" }
    }
  ]
}

OAuth

OAuth errors follow RFC 6749:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

Common errors

"Relay not connected"

The relay for the requested home is offline. No device commands can be routed.

Fix: Relay Offline troubleshooting

"Accessory not found"

The accessory ID doesn't exist, or your token doesn't have access to its home.

• Check the ID is correct — use GET /rest/state to list all accessible accessories
• Check your token's home permissions include the right home

"Insufficient permissions"

Your token has view access to this home but the operation requires control.

Fix: Create a new token with control permission. See Authentication → Access Tokens.

"Token expired"

JWT tokens expire after their configured lifetime. Access tokens expire if an expiry was set at creation.

• For JWTs: re-authenticate (sign in again)
• For access tokens: create a new one, or use a token with no expiry

"Home not found"

The home ID doesn't exist or your token can't see it.

• List accessible homes: GET /rest/state shows all homes your token can access
• Check your token's homePermissions field

"Characteristic not writable"

You're trying to set a read-only characteristic (e.g., temperature sensor reading, battery level).

Only control characteristics are writable: on, brightness, hue, saturation, targetTemperature, lockTargetState, etc.

"Invalid value"

The value is out of range for the characteristic type:

Characteristic	Valid range
brightness	0–100
hue	0–360
saturation	0–100
targetTemperature	Depends on device min/max
volume	0–100
targetPosition	0–100

---

Authentication reference: Authentication

REST API reference: REST

GraphQL reference: GraphQL