Error handling

All error responses follow this format:

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

HTTP status	Error code	Description
400	`invalid-payload`	Invalid JSON or missing required fields.
401	`unauthorized`	Invalid API key or IP not in allowlist.
404	`session-not-found`	Session does not exist or does not belong to this integration.
500	`internal-server-error`	Server error.

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.

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.

Session timeout — sessions expire after the configured timeout (default: 24 hours).
Webhook timeout — your webhook endpoint must respond within 30 seconds.
Webhook retries — failed webhook deliveries are retried up to 5 times with exponential backoff (250 ms to 2 seconds).
Message content — messages must contain either text or attachments. Empty messages are rejected.