A failed request gets an HTTP error status and a JSON body with one error object:
{
"error": {
"message": "to: Invalid",
"code": "VALIDATION_ERROR",
"statusCode": 400
}
}
message says what went wrong and is written for a developer to read. statusCode repeats the HTTP status. code, when present, is a stable value you can branch on in your code. Some errors also carry a details object with more to act on.
Status codes
| Status | Meaning |
|---|---|
| 400 | The request is malformed. For a body that fails validation, code is VALIDATION_ERROR and message names each field that failed, such as to: Invalid. |
| 401 | The x-api-key header is missing, or the key isn't valid. See Authentication. |
| 403 | The request isn't allowed. Cases you may meet: the resource belongs to another workspace; on POST /outbound, the workspace has reached its monthly usage limit (USAGE_LIMIT_EXCEEDED) or a trial has used its included minutes (TRIAL_LIMIT_REACHED); on POST /outbound and POST /sms/send, the account is suspended for an overdue invoice (ACCOUNT_SUSPENDED). |
| 404 | The route doesn't exist (Route not found) or the item wasn't found. |
| 409 | On POST /outbound, the workspace's calling rules refused the call: calls are turned off for the workspace (CALLS_DISABLED; portal Settings, Calling) or the number is on its do-not-call list (DO_NOT_CALL). Nothing was queued, and the same request gets the same answer until the rule changes. See Placing outbound calls. On POST /sms/send (IDEMPOTENCY_KEY_IN_USE), an earlier request with the same Idempotency-Key has not finished, its outcome is unknown, or it went out (error.details.providerSid, when present). Retrying with the same key, a few seconds apart and within hours, is safe; if the 409 lasts more than a minute, stop and treat the text as possibly delivered. Never resend it under a new key. See Sending texts. |
| 422 | On POST /sms/send, the recipient cannot take the text (RECIPIENT_OPTED_OUT, LANDLINE_OR_UNREACHABLE), or the Idempotency-Key was already used for a different text (IDEMPOTENCY_KEY_REUSED): a fault in the request rather than the recipient, and the key's first text may already have gone out. Branch on code. See Sending texts. |
| 429 | Too many texts sent or statuses read for the workspace this minute (RATE_LIMITED). Nothing was done; try again in a minute. On POST /sms/send, retry with the same Idempotency-Key once the next minute starts. |
| 500 | Something failed while handling the request. Read message before treating it as an outage, as it may name the problem. On POST /sms/send, retry with the same Idempotency-Key. |
| 502 | On POST /sms/send, the text may have gone out (SMS_SEND_OUTCOME_UNKNOWN) or did (SMS_SENT_NOT_RECORDED): do not resend those. SMS_PROVIDER_UNREACHABLE means the carrier could not be reached and nothing was sent: retry with the same Idempotency-Key. SMS_PROVIDER_REFUSED means the carrier refused the text: check error.details.providerErrorCode before you send it again. If you send it again, use the same Idempotency-Key. On GET /sms/messages/{id}, SMS_STATUS_UNAVAILABLE means the status could not be read: try again later. See Sending texts. |
| 503 | The service is briefly unavailable; try again shortly. On POST /sms/send, a 503 with a code means this request sent nothing (an earlier attempt under the same key may have), and any 503 is retried with the same Idempotency-Key, except after IDEMPOTENCY_KEY_HELD, which needs a new key. |
On POST /outbound and POST /sms/send, a from number that isn't in your workspace answers 404.
A request for a single conversation that doesn't exist yet isn't an error: GET /conversation/{id} answers 200 with "data": null until the call has ended.
Handling errors
- Log message, code and statusCode with your own request details. If you contact support@telvana.com about a failure, include them.
- After a 400, 401 or 403, the same request gets the same answer until you fix what it names. Some fixes are to the request. Others are to your account or the agent, such as ACCOUNT_SUSPENDED or SMS_NOT_ENABLED: after those, send the same request again if it is still wanted, on POST /sms/send with the same Idempotency-Key.
- Be careful about resending POST /outbound after a timeout or a 500. The call may already be queued, and a second request calls the same person again. Placing outbound calls covers how to check.
- On POST /sms/send, retry a timeout, a dropped connection or a 5xx with no code with the same Idempotency-Key, never a new one. The text may already have gone out. Retry within hours, not weeks: keys are not kept forever, so a late retry of a text that may have gone out could send it again.