Errors

Every refusal, on the home network, the relay, the WebSocket and MCP alike, has one shape (Error):

{ "error": { "code": "agent_access_disabled", "message": "…", "appAction": "integrations.record", "retryAfter": 2 } }

code is stable; message is plain English for the user and the agent, and never contains device paths, system errors or radio frames.
appAction (when set) names the IGH app screen that does what the API won't. Tell the user to go there.
retryAfter (seconds, when set) also comes as a Retry-After header on 429 and 503.
Anything not exposed, or not existing, is 404 not_found, never "forbidden".

Codes

Code	Status	When
`invalid_request`	400	A malformed request or message.
`unauthorized`	401	No credential, or an unknown, revoked or wrong-gateway one, or its integration was deleted.
`session_expired`	401	An agent session past its time (1 hour unused, 12 hours at most).
`record_disabled`	403	The integration is turned off.
`agent_access_disabled`	403	An agent or session credential while Agent access is off.
`cloud_access_disabled`	403	A request through the cloud while Cloud access is off.
`structural_not_allowed`	403	Creating, moving or deleting a room, floor or unit; renaming without structural on; renaming the exposure's own boundary.
`unlock_not_allowed`	403	Unlocking or opening with allow_unlock off.
`config_not_allowed`	403	An intent change without advanced_config read_write, or any intent with it off.
`not_offered`	403	Something the API never does: pairing units, side buttons, the units' own schedules, reading a menu over IGHC, resetting a unit, deleting objects.
`not_found`	404	Anything not exposed, or not existing. Never "forbidden".
`revision_mismatch`	409	The object changed since it was read (ifRevision differs).
`not_cached`	409	A setting packed with others has no cached value to change: read the unit's menu in the app first.
`unit_limit`	409	The unit has no free slot.
`version_unsupported`	410	An API version this gateway no longer serves.
`too_large`	413	A request body over 16 KiB through the cloud, or an answer over 4 MiB.
`validation`	422	A value out of range or of the wrong type.
`rate_limited`	429	Too many requests through the cloud: wait retryAfter seconds.
`internal`	500	The gateway failed (its store).
`not_implemented`	501	A part of the model that isn't built yet (for example the sleep unit mode).
`ighc_unavailable`	503	The gateway's IGHC adapter can't carry frames right now.
`gateway_offline`	503	Through the cloud: the gateway is not connected.
`unit_unreachable`	504	The unit didn't answer over IGHC.
`gateway_timeout`	504	Through the cloud: the gateway didn't answer within 10 seconds.

appAction

The IGH app screen a refusal points to. Tell the user to go there.

appAction	Screen
`integrations`	Settings → Integrations: add an API integration.
`integrations.record`	This API integration's page: what it shows, its settings, keys and agents.
`integrations.approve`	The Accept agent screen, opened from its notification.
`unit`	The unit's page.
`unit.menus`	The unit's page → Read menu (refreshes the cached settings).
`unit.schedules`	The unit's own schedules.
`unit.buttons`	The unit's side buttons.
`units.add`	Adding a unit.
`rooms`	Rooms and floors: create, move, delete.
`cloud.account`	The gateway's cloud account.

Examples

Turn on the garage light (not exposed to this integration).

POST /v1/devices/8F3K2M9Q4T7W:5b0e6c1a-2f4d-4c3b-9a8e-7d6f5e4c3b2a:u-garage/control

{
  "op": "set_power",
  "args": {
    "on": true
  }
}

Answer 404:

{
  "error": {
    "code": "not_found",
    "message": "Not found: nothing with this id is shown to this integration."
  }
}

IGH home API 1.1.0. Generated from the doc source; do not edit.