Errors

The Bandwidth Programmable Voice API will report call errors via Webhooks to the call status URL defined in your voice application.

Errors can also be found for a specific call by querying the call.

HTTP Status Codes

400 Bad Request

Bandwidth will return a HTTP-400 Error when the request is malformed or invalid. See the message of the error for tips before trying again.

HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8

{
  "type"        : "validation",
  "description" : "Invalid to: must be an E164 telephone number",
  "id"          : null
}

401 Unauthorized

Bandwidth returns a HTTP-401 Error when the specified user does not have access to the account. Ensure the username and password are correct along with the correct account number. See the credentials guide for more information.

HTTP/1.1 401 Unauthorized
Content-Type: application/json;charset=UTF-8

{
  "type"        : "authentication-error",
  "description" : "The credentials provided were invalid",
  "id"          : null
}

403 Forbidden

Bandwidth returns a HTTP-403 error when the user does not have access to the Voice API.

HTTP/1.1 403 Forbidden
Content-Type: application/json;charset=UTF-8

{
  "type"        : "authorization-error",
  "description" : "Access is denied",
  "id"          : null
}

404 Not Found

Bandwidth returns a HTTP-404 when the call-id is no longer active, or the path is not found. Ensure the call-id of the request is correct and adjust the request path accordingly.

HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8

{
  "type"        : "validation",
  "description" : "Call [{{invalid-call-id}}] not found",
  "id"          : null
}

405 Method Not Allowed

Bandwidth will return a HTTP-405 Error when the HTTP method used in the request is invalid. Check the allowed HTTP methods for this endpoint

HTTP/1.1 405 Method Not Allowed
Content-Type: application/json;charset=UTF-8

{
  "type"        : "validation",
  "description" : "Method Not Allowed",
  "id"          : null
}

409 Conflict

Bandwidth returns a HTTP-409 error when modifying a call that is unable to be modified. Such as a recently ended call or a call that has yet to be answered.

HTTP/1.1 409 Conflict
Content-Type: application/json;charset=UTF-8

{
  "type"        : "validation",
  "description" : "Call [{{call-id}}] cannot be modified in its current state",
  "id"          : ""
}

415 Invalid Media Type

Bandwidth returns a HTTP-415 error when the content-type of the request is incorrect. Ensure the request header contains Content-Type: application/json; charset=utf-8 and try again.

HTTP/1.1 415 Unsupported Media Type
Content-Type: application/json;charset=UTF-8

{
  "type"        : "validation",
  "description" : "Content type 'text/plain;charset=UTF-8' not supported",
  "id"          : null
}

429 Too Many Requests

Bandwidth returns a HTTP-429 error when the rate limit has been reached.

For more information about rate limits and queue management, see the guide on handling rate limits.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json;charset=UTF-8

{
  "type"        : "error",
  "description" : "Account call creation rate limit exceeded",
  "id"          : ""
}

500 Internal Server Error

Bandwidth will return a HTTP-500 Error when an unknown error occurs. If you receive a HTTP-500 error from the Bandwidth Programmable Voice API, please open a support ticket with the original request and the response returned. Please be sure to remove any passwords or sensitive information from the support ticket.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json;charset=UTF-8

{
  "type"        : "internal-error",
  "description" : "An unknown internal error occurred",
  "id"          : null
}

503 Unavailable

Bandwidth will return a HTTP-503 Error if the service is unavailable for some reason, such as when there are no servers available to serve the request or if the system is at capacity. If you receive a HTTP-503 error from the Bandwidth Programmable Voice API, please try the request again. If you continue to receive HTTP-503 errors, please open a support ticket with the original request and the response returned. Please be sure to remove any passwords or sensitive information from the support ticket.

HTTP/1.1 503 UNAVAILABLE
Content-Type: application/json;charset=UTF-8

{
  "type"        : "system-overloaded",
  "description" : "Managing too many concurrent calls",
  "id"          : null
}