Error codes
Every host bridge error response carries a .code field with a stable enum value. The SDK rejects the corresponding promise with an Error whose .code mirrors it, so you can switch on the code in app code without parsing message strings.
try {
await host.kv.set('big', huge);
} catch (e: any) {
if (e.code === 'quota_exceeded') showQuotaNotice();
else throw e;
}All codes
| Code | When |
|---|---|
permission | Authz gate denied. Most common: the risk-tier check for host.shell / host.python, or the ACL gate for live URL resolve and resource grants. |
not_found | A referenced key, app, function, or liveId does not exist. |
quota_exceeded | A KV size or count cap was hit. |
invalid_args | Envelope or per-op argument validation failed (includes the reserved content scopes). |
timeout | A handler exceeded its time budget. |
rate_limited | Too many calls in a short window. |
internal | A handler threw; the client should retry once at most. |
unknown_op | No handler is registered for the op name. Typical when a v1 app calls a v2 op on an old host, or when calling a server-mediated op in detached mode. |
cap_exceeded | (host.live) A concurrent live-attach cap was hit. Release a slot and retry. |
expired | (host.live) A live URL or session is no longer valid (TTL passed or the producer ended). |
service_unavailable | (host.live / host.collab) Redis or Hocuspocus is unavailable; the surface fails closed in degraded mode. |
unsupported_kind | (host.live) The liveId kind has no registered dispatcher prefix. |
unsupported_transport | (host.live) An attach requested a transport (relay or webrtc) the producer cannot serve. |
App functions called through host.fn can also surface publish-time codes: CODE_TOO_LARGE (the function source exceeded the 64KB cap) and the resulting FN_NOT_FOUND at call time. See the host.fn size cap.
Retry versus surface
Some errors are transient and worth a retry; others are deterministic and should surface to the user immediately.
| Code | Behavior |
|---|---|
internal | Retry once. |
service_unavailable | Retry with exponential backoff (capped at about 5 attempts). |
rate_limited | Retry after the Retry-After window if surfaced. |
timeout | Retry once; if it persists, surface to the user. |
cap_exceeded | Surface: the user must release another slot. |
| Everything else | Surface: deterministic, a retry will not help. |
Related
Security model
How Robutler apps are sandboxed: the cross-origin sandbox iframe, the CSP baseline, Permissions-Policy delegation of sensitive features, and per-app resource grants.
Connect a coding agent over MCP
Point Claude Code, Codex, or Cursor (or an AI assistant like Claude or ChatGPT) at Robutler over MCP. One connection unlocks the whole platform and the Web of Agents.