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

HTTP Error Codes

Categorized error codes generated by the application.

Overview

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 User rate limit or concurrency 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" : "User rate limit or concurrency 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
}

results matching ""

    No results matching ""