Errors

Every non-2xx response carries a JSON body with the HTTP status, a short machine code, and a human message:

{ "statusCode": 400, "error": "Bad Request", "message": "..." }

Validation failures (400) include a field-level breakdown under message so you can show inline form errors. The SDKs throw a typed error (VoyloApiError) carrying .status and .body.

Status codes

• 400 Bad Request — invalid input (bad/missing fields, bad enum). Don't retry without fixing the request.
• 401 Unauthorized — missing/expired session or invalid API key. Re-authenticate.
• 403 Forbidden — your workspace role doesn't permit this action (see roles), or you're not a member of the workspace.
• 404 Not Found — the resource doesn't exist in this workspace.
• 409 Conflict — a uniqueness clash (e.g. importing a number that already exists).
• 5xx — a server-side problem. Safe to retry idempotent GETs with backoff; for mutations, check whether it applied before retrying.

Authentication

Programmatic requests use an API key as a bearer token plus the X-Workspace-Idheader. A 401 means the key is wrong or revoked; a 403 means the key's workspace doesn't allow the action.

Call outcomes vs API errors

A call that doesn't connect (no-answer, busy, all destinations down) is notan API error — it's recorded on the call record's outcome and routing attempts, and emitted as a call.completed / call.failed webhook. Watch those, not API status codes, for call-level results.