Skip to main content

Error handling

Error handling​

All error responses follow this format:

{
  "error_code": "string",
  "error_message": "string"
}
HTTP statusError codeDescription
400invalid-payloadInvalid JSON, missing required fields, or a value outside the accepted set.
401invalid-api-keyMissing or invalid API key.
401unauthorizedIP not in allowlist.
404session-not-foundSession does not exist, has expired, or does not belong to this integration.
410integration-not-foundThe integration has been deleted. Stop retrying and remove the stored credentials.
500internal-server-errorServer error.

error_message carries the specific reason for a 400, for example "channel_type" must be one of: chat, email, voice or A session cannot have more than 25 tags.

Troubleshooting​

Webhook not receiving events
  • Verify your webhook_url is publicly accessible over HTTPS.
  • Check that your server returns a 2xx status code within a few seconds.
  • Confirm subscribed_events includes the event types you expect, or leave it empty to receive all events.
401 Unauthorized on inbound API
  • Verify the API key in your Authorization header matches the one generated in the Moveo dashboard.
  • Use the format Authorization: apikey YOUR_API_KEY (note the apikey prefix).
  • If you configured an IP allowlist, confirm your server's IP address is included.
404 Session not found
  • Confirm the session_id matches the value returned from the create session endpoint.
  • The session may have expired (default timeout: 24 hours). If so, create a new session and retry the request with the new session_id.
  • Check that the session belongs to the same integration_id used in the request.
410 Integration not found
  • The integration has been deleted in the Moveo dashboard. This is permanent, and a retry does not succeed.
  • Stop the retry loop, discard the stored API key, and create a new integration if you still need the connection.
400 Invalid payload
  • Verify the request body is valid JSON.
  • For send message requests, ensure either text or attachments is provided.
  • Check that required fields (like filename and content_type for file uploads) are present.
  • For create session, channel_type must be chat, email, or voice if you send it at all.
  • For the tag endpoints, tags must contain at least one non-empty value, and the session must not end up with more than 25 tags.

Limitations​

  • Session timeout: sessions expire after the configured timeout (default: 24 hours).
  • Webhook timeout: your webhook endpoint must respond within 8 seconds.
  • Webhook retries: a delivery is attempted at most 3 times in total. Only 408, 429, 500, 502, 503, and 504 responses are retried; timeouts are not. Backoff runs from 250 ms to 2 seconds, except for a 429 carrying a Retry-After, which Moveo honors up to 60 seconds. See retry timing.
  • Message content: messages must contain either text or attachments. Empty messages are rejected.
  • Text length: Moveo keeps the first 1,500 characters of input.text and drops the rest. The API does not return an error for a longer text.
  • Messages per session: while the AI agent handles a session, Moveo accepts up to 200 user messages. After that, the API returns 202 Accepted but Moveo drops the message. The limit does not apply after a handover.
  • Request body: a request to /v1/custom/* can be 10 MiB at most. A larger request gets 413 Request Entity Too Large.
  • Context: the context has no size limit of its own. It holds at most 25 tags and 250 variables in each channels object, and a variable name has at most 128 characters. See context object.
  • Handover: after a handover, the AI agent stays silent until you give the session back with the Moveo REST API. See after a handover.
  • Tags: a session carries at most 25 tags, each up to 48 characters after normalization.
Last updated on