Error handling

Error handling

All error responses follow this format:

{
  "error_code": "string",
  "error_message": "string"
}

HTTP status	Error code	Description
400	invalid-payload	Invalid JSON, missing required fields, or a value outside the accepted set.
401	unauthorized	Invalid API key or IP not in allowlist.
404	session-not-found	Session does not exist, has expired, or does not belong to this integration.
410	integration-not-found	The integration has been deleted. Stop retrying and remove the stored credentials.
500	internal-server-error	Server 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 — retrying will 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.
• Tags — a session carries at most 25 tags, each up to 48 characters after normalization.