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.

"Insufficient HomeKit privileges"

Different from "Insufficient permissions" above: this is about the relay's Apple Home rights, not your Homecast token. The relay Mac's Apple ID has view-only access to the home, so HomeKit automations can't be created or edited (error code INSUFFICIENT_HOMEKIT_PRIVILEGES, or Insufficient privileges from older relays).

View-only access is a supported configuration — device control, scenes, monitoring, and Homecast automations all work fully; only HomeKit-native automations are read-only.

To enable automation editing: In the Apple Home app, open Home Settings, tap the relay user, and enable "Add & Edit Accessories" (called "Allow Editing" on older iOS and macOS versions).

"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