Integrate
Errors
The {code, message} error shape and every public error code.
Every 4xx/5xx from the public endpoints (/v2/token, /v2/agents,
/v2/conversations, /v2/chat, /v2/runs) has the same shape:
{ "code": "invalid_token", "message": "Authentication failed" }Program against code (machine-readable), not message (human-readable —
it can change). Some errors add scope (e.g. budget_exceeded, queue_full) or
retry_after (e.g. rate_limited, queue_full).
Error codes
| Code | HTTP | Meaning |
|---|---|---|
invalid_token | 401 | The token is missing or invalid. |
token_expired | 401 | The token has expired — exchange a new one. |
invalid_publishable_key | 401 | The publishable key doesn't exist or was revoked. |
origin_not_allowed | 403 | The calling page's origin isn't on the allowed-origins list. |
invalid_user_hash | 401 | The user-hash signature doesn't match the identity secret. |
user_hash_expired | 401 | expires-at has passed — sign a new ticket. |
org_suspended | 403 | The organization is suspended. |
end_user_blocked | 403 | This end-user has been blocked. |
agent_not_found | 404 | The agent doesn't exist. |
agent_inactive | 409 | The agent is deactivated. |
conversation_not_found | 404 | The conversation doesn't exist. |
run_not_found | 404 | The run doesn't exist. |
run_not_cancellable | 409 | The run has already finished and can't be cancelled. |
approval_pending | 409 | This conversation has an action awaiting confirmation — approve or decline it before sending a new message. |
run_not_waiting | 409 | This run is not waiting for a decision (already decided, finished, or never paused). |
rate_limited | 429 | Too many requests — see retry_after. |
budget_exceeded | 429 | The daily token budget is used up — see scope. |
queue_full | 429 | The assistant is busy — retry after retry_after seconds; see scope (org or deployment). |
validation_error | 422 | The request body is invalid. |
redis_unavailable | 503 | Live streaming is temporarily unavailable — retry. |
internal_error | 500 | An error on Harnix's side — retry, or contact support if it persists. |
This is a closed list — no other code appears on the public endpoints.