API Reference
Errors
Conventional HTTP status codes, and a body that names what went wrong.
Shape of an error
Errors return a single object with a machine-readable code, a human-readable message, and — for validation failures — the field at fault.
{
"error": {
"code": "invalid_request",
"message": "to must be a phone number in E.164 format",
"field": "to"
}
}Status codes
| Status | Code | What it means |
|---|---|---|
| 401 | unauthorized | The API key is missing, malformed or revoked. |
| 403 | forbidden | The key is valid but lacks the scope for this call. |
| 404 | not_found | No resource with that id exists in your workspace. |
| 422 | invalid_request | A field failed validation. The body names the field. |
| 429 | rate_limited | You exceeded the request rate. Retry after the header says when. |
| 500 | server_error | Something broke on our side. Safe to retry. |
Retrying
Retry 429 and 5xx with exponential backoff and jitter. Never retry a 4xx
below 429 — the request will fail the same way every time. For sends, pass an
idempotency key so a retry cannot deliver twice.
Was this page helpful?