API reference
Errors
View as MarkdownThe API uses standard HTTP status codes. Successful responses are 2xx and usually include "status": "success". Failed responses carry a JSON body with a human-readable message, and most also include "status": "error". A few failures return a plain, non-JSON error page instead: a request body that is not valid JSON (400), and an upload rejected before it reaches the handler, such as an image over 1 MB or a file under the wrong field name (500). Each operation's Responses section notes these:
{ "status": "error", "message": "No chatbot associated with the provided chatbotId was found for the user."}Most property names are camelCase; webhook payloads and a few response fields are snake_case, as each page documents. Optional request fields can simply be omitted.
Status codes
| Status | Meaning | What to do |
|---|---|---|
| 400 | The request is invalid: a missing or malformed field, or a limit was reached (for example training characters). | Read message, fix the request, and retry. |
| 401 | Authentication failed, the workspace plan does not include API access, or the chatbot (or a create request's model) uses custom-model and the plan does not include custom models. | See Authentication, or plans. |
| 403 | The key can't reach the chatbot or operation: the chatbot is in another workspace or no longer exists, a chatbot-scoped key names another chatbot, a workspace-wide operation got a chatbot-scoped key, the plan lacks the feature (for example the SSO Login add-on), or a chatbot setting the operation needs is turned off (for example the conversation portal). | Check that the chatbot still exists and use a key from its workspace (a workspace key for workspace-wide operations), see plans, or turn the setting on in the chatbot's settings. |
| 404 | The conversation, action, sub-user or other resource was not found. /live-chat, /livechat-state and /bot-control answer 400 for a missing conversation, and /delete-file for a missing file, instead. | Check the id. |
| 429 | Too many requests. | Wait for Retry-After seconds; see Rate limits. |
| 5xx | Something went wrong on our side, or an upload was rejected before it reached the handler. | Retry with backoff; contact support if it persists. A rejected upload (file too large or wrong field name) fails again on retry: fix the request. |
Each endpoint page lists the statuses it returns under Responses.