Concepts
Errors
Every failure is a typed code with an HTTP status and a retryable flag — the same across HTTP, MCP, the SDK and the CLI.
Errors have one shape:
{
"error": { "code": "BUSY", "message": "profile already has a live session", "retryable": true, "details": { "session_id": "…" } },
"correlation_id": "6f1c…"
}Branch on code, never on message. details carries typed facts when there are any (the busy session, the field that failed validation, the limit that was reached). Quote correlation_id when you contact support or file feedback.
Codes
| Code | HTTP | Retryable | Meaning |
|---|---|---|---|
UNAUTHENTICATED | 401 | no | Missing, invalid, revoked or expired key |
FORBIDDEN | 403 | no | The key or its member lacks the capability |
REAUTH_REQUIRED | 403 | no | A sensitive action needs a fresh sign-in in the app |
NOT_FOUND | 404 | no | Nothing visible to you at that id |
VALIDATION_FAILED | 422 | no | Input does not match the schema; details lists fields |
CONFLICT | 409 | no | Stale expected_revision, or a reused command_id with another body |
BUSY | 409 | yes | The resource is in use (for example the profile is open) |
STALE_GRANT | 410 | no | A ticket or grant was superseded |
QUOTA_EXCEEDED | 429 | no | A workspace limit is reached |
RATE_LIMITED | 429 | yes | Too many requests; wait for Retry-After |
CAPACITY_UNAVAILABLE | 503 | yes | No capacity right now |
DEPENDENCY_UNAVAILABLE | 503 | yes | A service Browlix depends on did not answer |
UNSUPPORTED | 501 | no | Not supported here (for example by this worker version) |
NETWORK_UNHEALTHY | 424 | no | The proxy or network check failed |
INTEGRITY_FAILED | 422 | no | Data failed an integrity check |
OUTCOME_UNKNOWN | 202 | yes | Accepted, but the result could not be confirmed; check the receipt |
RECOVERY_REQUIRED | 409 | no | The last session ended uncertainly; recover it first |
SYNC_PENDING | 409 | yes | Another machine holds newer profile data |
FENCED | 409 | no | Your app hold on a session is no longer current; acquire it again |
UNKNOWN | 500 | no | Unexpected; report it with the correlation_id |
Retrying
Retry only codes marked retryable, with backoff, and — for commands — with the same command_id. The SDK does this for you on reads and same-id commands, honouring Retry-After up to 10 seconds.