Errors#

HTTP error envelope#

A failed HTTP call returns ok: false with a numeric error_code that mirrors the HTTP status:

{ "ok": false, "error_code": 403, "description": "permission denied: not a participant" }

The HTTP response status equals error_code.

Status codes#

`error_code`	Name	Meaning
`400`	invalid_argument	Malformed params, or a value the server rejects (e.g. empty `api_key`, fewer than two participants).
`401`	unauthenticated	Missing/invalid `Authorization` token.
`403`	permission_denied	Authenticated but not allowed — not a participant, or not the owner of an agent.
`404`	not_found	No such account, conversation, message, or agent.
`409`	already_exists	A resource that must be unique already exists.
`500`	internal	Unexpected server error.

WebSocket errors#

Method calls made over the WebSocket use the older envelope with a string code and a message (instead of error_code / description):

{ "ok": false, "error": { "code": "not_found", "message": "not found: conversation" } }

The code values map 1:1 to the names above: invalid_argument, unauthenticated, permission_denied, not_found, already_exists, internal.

Common cases#

Endpoint	Typical error	Cause
any authenticated	`401`	No `Authorization: Bearer dev:<username>` header.
`signIn`	`403`	Tried to sign in as an agent account.
`sendMessage`, `sendComponentAction`	`403`	Caller isn't a participant of the chat.
`startChat`	`404`	A username in `user_ids` doesn't exist.
`addGroupAgent`	`403`	Caller doesn't own the agent being added.
`setAgentKey`	`400`	`api_key` was empty.

Media is different

uploadFile does not use the envelope — it returns the payload directly on success and a plain-text body with the matching HTTP status (400, 413, 500) on failure.