Errors

Every error is JSON with a stable envelope:

json

{
  "error": {
    "code": "invalid_request",
    "message": "`to` must be a valid US/Canada number in E.164 format.",
    "param": "to"
  }
}

Codes

Status	Code	Meaning
400	`invalid_request`	A parameter is missing or malformed — `param` names it.
401	`invalid_api_key`	Missing, malformed, revoked, or unknown key.
403	`live_access_required`	Needs live access (or a live key before approval).
403	`test_mode_only`	Sandbox-only endpoint called with a live key.
403	`tenant_suspended`	Account suspended.
403	`forbidden`	Key is valid but can't act on this resource (e.g. a `from` you don't own).
404	`not_found`	No such resource on your account.
409	`idempotency_conflict`	Idempotency-Key reused with a different payload.
429	`rate_limited`	Too many requests — check `Retry-After`.
429	`quota_exceeded`	A daily quota was reached.
502	`carrier_error`	Upstream provider failure — retry with backoff.
500	`internal_error`	Our fault. Retry, and tell us if it persists.

Default 60 requests/minute per key. 429s include a Retry-After header. Successful quota-limited calls include X-Quota-Remaining.