Reference
Error codes
Every error code the API answers: what happened, why, and how to fix it.
A refused request answers a JSON body with an error code, a message, a requestId to quote to support, whether it is retryable, and a docslink to the code's page here. Authentication errors and the event and webhook routes answer a smaller body: error and message, sometimes details.
| Error | Status | What happened |
|---|---|---|
invalid_request | 400 | The request is not valid |
invalid_idempotency_key | 400 | The Idempotency-Key header is malformed |
unauthorized | 401 | No valid API key |
insufficient_scope | 403 | The key does not cover this |
no_project | 403 | The request names no workspace |
sms_refused | 403, 429 | The text was refused by the SMS rules |
wallet_refused | 402 | The balance cannot cover this message |
not_found | 404 | No such resource in this workspace |
capability_not_ready | 409 | The sender cannot do this right now |
recipient_opted_out | 409 | The person opted out |
idempotency_conflict | 409 | The Idempotency-Key names a different message |
window_closed | 409 | The channel's reply window is closed |
controller_conflict | 409 | The conversation has another controller |
controller_unsupported | 409 | This conversation cannot have that controller |
channel_not_priced | 409 | The channel has no delivery price |
channel_not_supported | 409 | This sender cannot send on that channel |
not_linkable | 409 | The send cannot become a conversation message |
number_inactive | 409 | The number is not active |
plugin_suspended | 409 | The channel is suspended for this workspace |
outcome_unknown | 409 | A provider attempt has no recorded result |
send_in_progress | 409 | A request with this Idempotency-Key is still in flight |
content_too_long | 422 | The text is longer than the channel takes |
media_too_large | 413 | The media is larger than the channel takes |
media_unavailable | 422 | The media could not be fetched or is not carried |
operation_not_supported | 422 | The channel does not support this yet |
output_refused | 422 | The output guard refused the text |
rate_limited | 429 | Too many requests |
channel_not_registered | 503 | The channel is reloading |
trust_unavailable | 503 | Message checks are briefly unavailable |
wallet_unavailable | 503 | The wallet is briefly unavailable |
messaging_unavailable | 503 | Sending is briefly unavailable |
provider_error | 502 | The provider did not take the message |
provider_retry_later | 503 | The provider is rate limiting this sender |
no_sender | 409 | Nothing to send from on this channel |
sender_ambiguous | 409 | Several senders could send this |
recipient_not_allowed | 403 | The channel does not allow this recipient |
test_mode_only | 403 | Only a test key can do this |
test_address_required | 422 | A test key can only reach a test address |
test_address_not_allowed | 422 | A live key cannot reach a test address |
test_limit_reached | 429 | The workspace's test allowance for today is used |
invalid_event_types | 400 | Unknown event types |
invalid_conversation_id | 400 | The conversationId is not a conversation id |
invalid_cursor | 400 | The cursor is not one this API returned |
cursor_expired | 410 | The cursor is older than the stream's replay window |
events_unavailable | 503 | Events are briefly unavailable |