Error response shape
All errors follow a consistent structure:| Field | Description |
|---|---|
type | Error category (see below) |
code | Machine-readable error code |
message | Human-readable explanation |
param | The parameter that caused the error (when applicable) |
request_id | Unique ID for debugging. Include this in support requests |
Error types
authentication_error (401)
The request could not be authenticated.
| Code | Meaning |
|---|---|
missing_api_key | No Authorization header provided |
invalid_api_key | Key format is wrong, key is revoked, or key has expired |
authorization_error (403)
The API key is valid but lacks permission.
| Code | Meaning |
|---|---|
insufficient_scope | The key doesn’t have the required scope for this endpoint |
line_not_accessible | The key is line-scoped and can’t access the requested line |
sandbox_not_activated | Your sandbox hasn’t been activated yet. Text the activation code to the sandbox number |
invalid_request_error (400)
The request is malformed or missing required data.
| Code | Meaning |
|---|---|
missing_required_parameter | A required query parameter or body field is missing |
invalid_parameter_value | A parameter has an invalid value (e.g. wrong ID prefix) |
invalid_json | The request body is not valid JSON |
sandbox_contact_mismatch | You can only send to your paired phone number on the sandbox line |
not_found_error (404)
The requested resource doesn’t exist.
| Code | Meaning |
|---|---|
line_not_found | No line exists with the given handle |
chat_not_found | No chat found for the given identifier on this line |
message_not_found | No message found with the given ID |
outbox_item_not_found | No outbox item found with the given ID |
webhook_not_found | No webhook found with the given ID |
rate_limit_error (429)
Too many requests. Back off and retry after the Retry-After header value.
| Code | Meaning |
|---|---|
rate_limit_exceeded | Hourly API rate limit exceeded |
sandbox_quota_exceeded | Daily sandbox limit of 50 messages reached. Resets at midnight UTC |
HTTP status codes
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Resource created |
| 204 | No content (OPTIONS preflight) |
| 400 | Bad request |
| 401 | Unauthorized |
| 403 | Forbidden |
| 404 | Not found |
| 429 | Rate limited (hourly API rate limit or daily sandbox quota exceeded) |