HTTP Errors when using MFA

Bandwidth will respond with HTTP error codes when there are any issues with Multi-Factor Authentication endpoints. Any 4xx or 5xx HTTP response code will not be billed. All of the errors except for 401 and 403 have a similar response format. Unifying all of the responses is in the works, so be sure to keep checking the page for updates!

Overview

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 429 - Too Many Requests
• 500 - Internal Server Error

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.

POST https://mfa.bandwidth.com/api/v1/accounts/{{accountId}}/code/messaging HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0

{
  "to"            : "",
  "from"          : "+12345678901",
  "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
  "scope"         : "2FA",
  "digits"        : 7,
  "message"       : "Test code: {CODE}"
}

Status: 400 Bad Request
Content-Type: application/json; charset=utf-8

{
  "error": "to number is required",
  "requestId": "abc12312-abcd-1234-abcd-1234abcd1234"
}

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.

POST https://mfa.bandwidth.com/api/v1/accounts/{{accountId}}/code/messaging HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0

{
  "to"            : "+12345678901",
  "from"          : "+12345678901",
  "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
  "scope"         : "2FA",
  "digits"        : 7,
  "message"       : "Test code: {CODE}"
}

Status: 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
    "message": "Unauthorized"
}

403 – FORBIDDEN

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

POST https://mfa.bandwidth.com/api/v1/accounts/{{accountId}}/code/messaging HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0

{
  "to"            : "+12345678901",
  "from"          : "+12345678901",
  "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
  "scope"         : "2FA",
  "digits"        : 7,
  "message"       : "Test code: {CODE}"
}

Status: 403 Forbidden
Content-Type: application/json; charset=utf-8

{
   "Message": "User is not authorized to access this resource with an explicit deny"
}

429 - TOO MANY REQUESTS

Bandwidth returns a HTTP-429 error when the rate limit has been reached. This response code gets returned when the verify endpoint is called too many times with invalid codes.

POST https://mfa.bandwidth.com/api/v1/accounts/{{accountId}}/code/verify HTTP/1.1
Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0
Content-Type: text/plain;charset=UTF-8

{
  "to"                       : "+12345678901",
  "applicationId"            : "93de2206-9669-4e07-948d-329f4b722ee2",
  "scope"                    : "2FA",
  "expirationTimeInMinutes"  : 3,
  "code"                     : "1234"
}

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

{
  "error": "This number has exceeded verification attempts, please wait 2 minutes",
  "requestId": "abc12312-abcd-1234-abcd-1234abcd1234"
}

500 - INTERNAL SERVER ERROR

Bandwidth returns a HTTP-500 error when there is an unintended interal error on our end.

POST https://mfa.bandwidth.com/api/v1/accounts/{{accountId}}/code/verify HTTP/1.1
Authorization: Basic YXBpVG9rZW46YXBpU2VjcmV0
Content-Type: text/plain;charset=UTF-8

{
  "to"                       : "+12345678901",
  "applicationId"            : "93de2206-9669-4e07-948d-329f4b722ee2",
  "scope"                    : "2FA",
  "expirationTimeInMinutes"  : 3,
  "code"                     : "1234"
}

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

{
  "error": "Internal Error",
  "requestId": "abc12312-abcd-1234-abcd-1234abcd1234"
}