Errors
Status codes, response shape, and common failure modes.
Errors are returned as JSON with a consistent shape:
{
"error": "dnc_blocked",
"message": "Destination +14155551234 is on the global DNC list.",
"details": {
"suppression_source": "global"
}
}
error — stable machine-readable code. Safe to switch on.message — human-readable. Safe to surface to end users in your UI (no
PII or secrets).details — optional, error-specific data.
| Status | Meaning |
|---|
400 Bad Request | Malformed request — missing field, bad type, invalid E.164, etc. |
401 Unauthorized | Missing / invalid Authorization header, revoked key, expired key. |
403 Forbidden | Key is valid but lacks the required scope, is restricted to a different number_id, or the account is verification_status=pending_review. |
404 Not Found | Resource doesn't exist or doesn't belong to your tenant. |
409 Conflict | Idempotency-Key reused with a different body. |
422 Unprocessable Entity | Validation failed on an otherwise well-formed request (e.g. objective too long, invalid outcome_schema shape). |
429 Too Many Requests | Rate limit exceeded — see Rate limits. |
5xx | Server error. Safe to retry with the same Idempotency-Key. |
error | Meaning |
|---|
dnc_blocked | Destination is on global or your tenant's DNC list. |
call_hours_violation | Time-of-day restriction (TCPA) would be violated. |
no_active_number | No Twilio subaccount configured or no active number selected. |
invalid_phone | to is not a valid E.164 NANP number. |
outcome_schema_invalid | Your schema doesn't parse as a valid OpenPhn outcome schema. |
verification_pending | Account hasn't been approved yet. |
rate_limited | Per-key rate budget exhausted. |
error | Meaning |
|---|
invalid_token | Bearer header missing or wrong format. |
key_revoked | Key was explicitly revoked. |
key_expired | Rotation grace period elapsed. |
scope_required | Your key doesn't have the scope this endpoint needs. |
number_not_allowed | Your key is pinned to number_ids and this target isn't in the allowlist. |
dashboard_only | You sent a session JWT to a /v1/* route — use an API key. |
- 5xx / network error / timeout → retry with the same
Idempotency-Key,
exponential backoff (e.g. 1s, 2s, 4s, 8s; cap at 3–4 attempts).
- 429 → honor
Retry-After.
- 4xx other than 429 → do not retry. The request is wrong; fix and
resubmit.