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. Branch on the numeric statusCode and the stable error string rather than the human message, which may change.

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.