Errors during an active call
Errors that occur during an active call will be delivered to the disconnectUrl
for outbound calls and Call status callback URL
for inbound calls in the form of a Disconnect event. Example errors:
- Invalid BXML returned by a callback
- Unable to reach the callback url
- Callback URL returns a 4XX or 5XX response code
- User rate limits are reached
- System rate limits are reached
Errors can also be found for a specific call by querying the call using the API.
HTTP Error Codes
Categorized error codes generated by the application.
Overview
- 400 - Bad Request
- 401 - Unauthorized
- 403 - Forbidden
- 404 - Not Found
- 405 - Method Not Allowed
- 409 - Conflict
- 415 - Invalid Media-Type
- 429 - Too Many Requests
- 500 - Internal Server Error
- 503 - Unavailable
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.
Validation Errors
Type | Message |
---|---|
validation | Bad Request |
validation | Invalid to: must be an E164 telephone number |
validation | Invalid from: must be an E164 telephone number |
validation | Missing at least one required field. Required fields are [from, to, answerUrl, applicationId] |
validation | ${0} must be within the range [${1} , ${2} ], but was ${3} |
validation | Could not create call: sendCallback tag must contain at most ${0} characters |
validation | Invalid answerUrl: only http and https are allowed |
validation | Invalid answerUrl method. Supported methods: [POST, GET] |
validation | Could not create call: Application id ${0} not found |
validation | There is something wrong with the request |
Example: Invalid TO telephone number
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "scooby-doo",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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 security & credentials guide for more information.
Authorization Errors
Type | Message |
---|---|
authentication-error | Unauthorized |
authentication-error | The credentials provided were invalid |
authentication-error | Invalid basic authentication token |
authentication-error | Failed to decode basic authentication token |
Example: Incorrect credentials sent
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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.
Forbidden Errors
Type | Message |
---|---|
authorization-error | Forbidden |
authorization-error | Access is denied |
Example: User does not have access
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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.
Call Not found errors
Type | Message |
---|---|
validation | Call [${0} ] not found |
Nonexistent Path errors
Type | Message |
---|---|
validation | Not Found |
Example 1 of 2: Updating a call that does not exist
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/{{invalid-call-id}} HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"type" : "validation",
"description" : "Call [{{invalid-call-id}}] not found",
"id" : null
}
Example 2 of 2: Path does not exist
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/invalid-path/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
HTTP/1.1 404 Not Found
Content-Type: application/json;charset=UTF-8
{
"type" : "validation",
"description" : "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
Validation Errors
Type | Message |
---|---|
validation | Method Not Allowed |
Example: Invalid HTTP method
DELETE https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "scooby-doo",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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.
Type | Message |
---|---|
validation | Call [${0} ] cannot be modified in its current state |
Example: Modifying a recently ended call
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/{{call-id}} HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"state" : "completed"
}
Responds
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 - UNSUPPORTED 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.
Type | Message |
---|---|
validation | Unsupported Media Type |
validation | Content type ${0} not supported |
Example: No Content-Type included
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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.
Type | Message |
---|---|
error | Account call creation rate limit exceeded or Account concurrent call limit exceeded |
Example: No Content-Type included
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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 – BACKEND
Bandwidth will return a HTTP-500
Error when an unknown error occurs. If you receive a HTTP-500
error from the Bandwidth 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.
Internal Server Errors
Type | Message |
---|---|
internal-error | Internal Server Error |
internal-error | An unknown internal error occurred |
Example: 500 Returned
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
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 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.
Unavailable Errors
Type | Message |
---|---|
system-overloaded | Handling too many requests |
system-overloaded | Managing too many concurrent calls |
POST https://voice.bandwidth.com/api/v2/accounts/{{accountId}}/calls/ HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
{
"from" : "+15552676804",
"to" : "+15555554444",
"answerUrl" : "http://www.myapp.com/hello",
"applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}
Responds
HTTP/1.1 503 UNAVAILABLE
Content-Type: application/json;charset=UTF-8
{
"type" : "system-overloaded",
"description" : "Managing too many concurrent calls",
"id" : null
}