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. Two cases you may meet: the resource belongs to another workspace, or, on POST /outbound, the workspace has reached its monthly usage limit (USAGE_LIMIT_EXCEEDED). |
| 404 | The route doesn't exist (Route not found) or the item wasn't found. |
| 500 | Something failed while handling the request. |
A few lookups that fail, such as a from number that isn't in your workspace, currently answer 500 with a message that names the problem, so read message before treating a 500 as an outage.
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.
- Fix the request before sending it again after a 400, 401 or 403. Sending the same request again gets the same answer.
- 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.