Developer docs

Errors

Every failed request has a non-2xx status and the same JSON body. Branch on the error code, not on the message text.

Error format

JSON

Error body (JSON){
  "error": "agent_paused",
  "message": "(A human-readable explanation, worded by Haven.)",
  "reason": "credits_exhausted"
}

error is a stable code that does not change once released. message is written for people and may be reworded. Some errors add fields, for example retryAfterSeconds for rate limits or issues for a request that failed validation.

Error codes

Codes that only the dashboard login screens or Haven’s own staff can trigger are left out of this list.

Authentication and sessions

Authentication and sessions
Code	Meaning
`not_authenticated`	No session cookie or API key was sent.
`invalid_api_key`	The API key is malformed, unknown or revoked.
`origin_not_allowed`	The website making the request is not on the allowed list (for the chat widget: the widget's allowed websites).

Permissions

Permissions
Code	Meaning
`forbidden`	Logged in, but this role cannot do this.
`session_required`	Only available to a logged-in dashboard user, not to API keys.

Limits

Limits
Code	Meaning
`rate_limited`	Too many requests; see retryAfterSeconds.
`payload_too_large`	The request body is too large.

Request shape

Request shape
Code	Meaning
`invalid_request`	Validation failed; see issues.
`invalid_json`	The body is not valid JSON.
`not_found`	No such resource for your account.

Billing and subscriptions

Billing and subscriptions
Code	Meaning
`invalid_plan`	The plan does not exist for this agent.
`same_plan`	Already on that plan.
`rail_unavailable`	That payment method is not configured.
`already_subscribed`	There is already a subscription for this agent.
`not_subscribed`	There is no subscription for this agent.
`plan_change_unavailable`	The subscription cannot change plan in its current state.
`plan_change_unsupported`	Plan changes are not available for this payment method.
`plan_change_failed`	The payment provider refused the plan change.
`checkout_failed`	The payment provider could not start checkout.
`no_billing_account`	There is no card subscription yet, so there is no card billing account.
`billing_portal_failed`	The payment provider could not open the billing portal.
`cancel_not_applicable`	Prepaid subscriptions end on their own; there is nothing to cancel.
`cancel_failed`	The payment provider refused the cancellation change.
`not_cancelling`	The subscription is not set to cancel, so there is nothing to reactivate.
`subscription_ended`	The billing period is over; subscribe again instead.

Agent engine

Agent engine
Code	Meaning
`agent_not_found`	Unknown agent.
`agent_paused`	The agent is paused for your account; see reason and message.
`agent_not_configured`	Your account has not set up this agent yet.
`conversation_not_found`	No such conversation for your account.
`conversation_busy`	The conversation is still answering a previous message.
`conversation_full`	The conversation is too long; start a new one.
`not_pending`	The approval was already decided.
`engine_unavailable`	The agent engine is not configured.
`model_unavailable`	The AI model service rejected or could not complete the request.

Knowledge

Knowledge
Code	Meaning
`invalid_url`	The website address cannot be used.
`not_verified`	The website is not verified yet.
`crawl_in_progress`	A crawl of this site is already queued or running.
`knowledge_unavailable`	Knowledge indexing is not configured.
`subscription_required`	Knowledge work needs an active subscription with credits; see reason.
`crawling_paused`	Crawling stopped because the site lost its verification; verify it again.
`document_limit_reached`	The plan allows no more documents; see limit.
`invalid_file`	The uploaded file is empty or unnamed.
`unsupported_file_type`	The file type, declared type and content must be a PDF or UTF-8 text.
`file_too_large`	The file exceeds the size or page limit.
`unreadable_pdf`	The PDF could not be read.
`no_text`	No readable text in the file.
`captcha_failed`	The anti-bot check did not pass; reload the page and try again.
`captcha_unavailable`	The anti-bot check could not run; try again shortly.
`agent_required`	This business has more than one agent: say which one with agent_id.

Channels (WhatsApp, email) and platform switches

Channels (WhatsApp, email) and platform switches
Code	Meaning
`channel_unavailable`	The channel is not available yet (coming soon) or not configured on this server.
`channel_not_found`	No such channel connection.
`models_halted`	The AI models are paused by an emergency stop.
`purchases_halted`	New purchases are paused by an emergency stop.
`signups_halted`	New sign-ups are paused by an emergency stop.
`invalid_attachment`	One of the attached files is not available.
`idempotency_key_reused`	The Idempotency-Key was already used with a different request.
`request_in_progress`	The first request with this Idempotency-Key is still running.
`account_suspended`	This account has been suspended. Contact support.

Chat widget (public endpoints)

Chat widget (public endpoints)
Code	Meaning
`widget_not_found`	Unknown or disabled widget id.
`visitor_session_required`	Widget calls need the visitor token from POST /widget/v1/:widgetId/sessions.
`visitor_session_expired`	The visitor token is unknown, expired, or from another site; start a new session.
`message_too_long`	The visitor message is longer than the widget allows; see maxChars.
`widget_cap_reached`	Your account's daily widget message cap is reached.
`challenge_failed`	The bot challenge was missing or did not pass.
`verification_failed`	No order matches that order number and email (deliberately generic).
`verification_unavailable`	This widget has no order verification set up.
`chat_unavailable`	The chat cannot answer right now (any internal reason; details are not shown to visitors).

Server

Server
Code	Meaning
`internal_error`	Something went wrong on our side.