Errors & rate limits

Every error response, regardless of status code, uses the same envelope:

{
  "error": {
    "type": "UnauthorizedException",
    "message": "Invalid or revoked API key",
    "details": { }
  }
}

details is only present for validation errors (e.g. a malformed request body) and mirrors the underlying field-level errors.

Common status codes

• 400 — malformed request, or the target device doesn't support the requested deliveryMethod (see Devices & capabilities).
• 401 — missing, malformed, unknown, or revoked API key; on unlock_attempts, also an incorrect code (counts against that code's attempt lockout — see Remote unlock).
• 403 — on unlock_attempts, the code's validFrom is in the future.
• 404 — the resource doesn't exist, or exists in the other mode (test vs. live) than your key.
• 409 — an Idempotency-Key was reused with a different request body; on unlock_attempts, also a code that's already been used or revoked.
• 410 — on unlock_attempts, the code's validUntil has passed.
• 429 — rate limit exceeded (see below).
• 503 — on unlock_attempts, the device wasn't reachable (e.g. bridge/gateway offline). Not the guest's fault — retry, the code stays valid.

Rate limits

Requests are limited to 10 requests/second (burst) and 200 requests/minute, tracked per client IP address (not yet per API key/tenant — if you call the API from a shared egress IP, factor that in).