Errors
Every REST API error uses the same envelope. name is stable and meant for code; message is an English sentence for humans and may change.
{
"statusCode": 422,
"name": "validation_error",
"message": "to: Invalid email address"
}
As a rule, 4xx means fix the request before sending it again; 429 and 5xx are temporary, so retry with backoff (see Limits). See also the error handling guide.
REST API
Code (name) | HTTP | Meaning and what to do |
|---|---|---|
validation_error | 422 | The request body or a parameter is invalid; message names the field. |
missing_required_field | 422 | A required field is missing. |
missing_api_key | 401 | No Authorization: Bearer header. |
invalid_api_key | 403 | The API key is unknown or revoked. |
restricted_api_key | 401 | The key lacks the scope this endpoint needs, or is locked to other origins. |
invalid_from_address | 403 | The from domain is not verified for this business (or not allowed for this key). |
not_found | 404 | The resource does not exist or belongs to another business. |
method_not_allowed | 405 | The HTTP method is not supported on this path. |
invalid_idempotent_request | 400 | The Idempotency-Key was used before with a different body. |
concurrent_idempotent_requests | 409 | Another request with the same Idempotency-Key is still running; retry shortly. |
rate_limit_exceeded | 429 | Too many requests; wait for retry-after seconds. |
daily_quota_exceeded | 429 | The plan's daily sending quota is used up. |
invalid_attachment | 422 | An attachment is malformed, unreachable (path) or too large. |
application_error | 500 | Something failed on our side; retry with backoff. |
internal_server_error | 500 | Unexpected error; retry with backoff and contact support if it persists. |
origin_not_allowed | 403 | The browser origin is not one of the site's domain or allowed origins. |
invalid_visitor_token | 401 | The visitor token is missing, expired or for another site; bootstrap again. |
invalid_agent_token | 401 | The agent token is missing or expired; sign in again. |
site_disabled | 403 | The chat site is turned off. |
invalid_app_key | 401 | The mobile app key (hak_…) is unknown or for another site. |
app_key_revoked | 403 | The mobile app key was revoked; ship a build with a new key. |
message_too_long | 422 | The message is longer than allowed (see Limits). |
unsupported_file_type | 422 | This file type cannot be uploaded. |
file_too_large | 413 | The file is larger than allowed (see Limits). |
conversation_closed | 409 | The conversation is closed and takes no new messages. |
product_not_enabled | 403 | The product is not available to this business. |
product_disabled | 403 | The business switched this product off (Settings → Modules). |
ai_budget_exhausted | 429 | |
ai_not_configured | 503 | |
ai_unavailable | 503 | |
instructions_full | 409 | |
forbidden | 403 | You are not allowed to do this. |
last_owner | 409 | A business must keep at least one owner. |
domain_taken | 409 | The domain is already used by another business. |
host_missing | 422 | A host name is required. |
host_mismatch | 422 | The host does not match the domain. |
slug_taken | 409 | The slug is already in use. |
slug_reserved | 422 | The slug is reserved. |
environment_mismatch | 403 | The resource belongs to the other environment (development vs production). |
no_bank_connection | 422 | Link a bank account before creating payments. |
code_taken | 409 | The order or payment code is already used. |
bank_link_failed | 422 | The bank refused the link; check the account details. |
invalid_otp | 422 | The confirmation code is wrong. |
otp_expired | 410 | The confirmation code expired; request a new one. |
invalid_state | 409 | The resource is not in a state that allows this action. |
provider_unavailable | 503 | The bank or invoice provider is not answering; retry later. |
invoice_provider_error | 422 | The e-invoice provider rejected the request; message has its reason. |
Realtime protocol
error frames on the websocket carry one of these in d.code; codes shared with the REST API mean the same.
| Code | Meaning |
|---|---|
validation_error | The request body or a parameter is invalid; message names the field. |
rate_limit_exceeded | Too many requests; wait for retry-after seconds. |
not_found | The resource does not exist or belongs to another business. |
unauthenticated | A frame arrived before auth succeeded. |
invalid_visitor_token | The visitor token is missing, expired or for another site; bootstrap again. |
origin_not_allowed | The browser origin is not one of the site's domain or allowed origins. |
site_disabled | The chat site is turned off. |
invalid_app_key | The mobile app key (hak_…) is unknown or for another site. |
app_key_revoked | The mobile app key was revoked; ship a build with a new key. |
conversation_closed | The conversation is closed and takes no new messages. |
file_too_large | The file is larger than allowed (see Limits). |
unsupported_file_type | This file type cannot be uploaded. |
bad_frame | The frame is not valid JSON or does not match the protocol schema. |
error | Any other failure for one request. |
SMTP relay
| Reply | Meaning |
|---|---|
535 5.7.8 | invalid credentials (wrong API key) |
530 5.7.0 | authentication required |
550 5.7.1 | unauthorized or forbidden (for example an unverified From domain) |
553 5.6.0 | invalid message (validation error) |
452 5.5.3 | more than 50 recipients |
421 4.7.0 | too many failed logins from this IP; try again later |
451 4.3.0 | temporary failure; retry |