HTTP Errors when sending messages

Bandwidth will respond with HTTP errors code when the message creation request fails. Any 4xx or 5xx HTTP response code will not be billed nor will the message be sent.

Overview

• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 415 - Invalid Media-Type
• 429 - Too Many Requests

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://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {user:password}

{
  "from"          : "",
  "to"            : "",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

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

{
  "type": "request-validation",
  "description": "Your request could not be accepted",
  "fieldErrors": [
    {
      "fieldName": "from",
      "description": "'from' must contain exactly one telephone number"
    },
    {
      "fieldName": "text",
      "description": "'text' is required unless media is included"
    },
    {
      "fieldName": "to",
      "description": "'to' must contain at least one telephone number"
    }
  ]
}

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://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {user:password}

{
  "from"          : "+19192676804",
  "to"            : "+19195554444",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

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

{
  "timestamp" : "2019-06-19T14:46:42.462+0000",
  "status"    : 401,
  "error"     : "Unauthorized",
  "message"   : "Bad credentials",
  "path"      : "/api/v2/users/{{accountId}}/messages"
}

403 – FORBIDDEN

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

POST https://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {user:password}

{
  "from"          : "+19192676804",
  "to"            : "+19195554444",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

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

{
  "timestamp" : "2019-10-10T19:32:28.236+0000",
  "status"    : 403,
  "error"     : "Forbidden",
  "exception" : "org.springframework.security.access.AccessDeniedException",
  "message"   : "Access is denied",
  "path"      : "/api/v2/users/asdf/messages/"
}

404 – NOT_FOUND

Bandwidth returns a HTTP-404 when the path is not found. Ensure the path of the request is correct and adjust accordingly.

POST https://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages/happy HTTP/1.1
Content-Type: application/json; charset=utf-8
Authorization: {user:password}

{
  "from"          : "+19192676804",
  "to"            : "+19195554444",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

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

{
  "timestamp": "2019-09-09T19:02:19.253+0000",
  "status": 404,
  "error": "Not Found",
  "message": "Not Found",
  "path": "/api/v2/users/{{accountId}}/messages/happy"
}

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.

POST https://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages HTTP/1.1
Authorization: {user:password}
Content-Type: text/plain;charset=UTF-8

{
  "from"          : "+19192676804",
  "to"            : "+19195554444",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

Status: 415 Unsupported Media Type
Content-Type: application/json; charset=utf-8

{
  "type": "unsupported-content-type",
  "description": "Content type 'text/plain;charset=UTF-8' not supported. Please use 'application/json'"
}

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 rate limits document.

POST https://messaging.bandwidth.com/api/v2/users/{{accountId}}/messages HTTP/1.1
Authorization: {user:password}
Content-Type: text/plain;charset=UTF-8

{
  "from"          : "+19192676804",
  "to"            : "+19195554444",
  "text"          : "Hello this is a text message",
  "applicationId" : "7fc9698a-b04a-468b-9e8f-91238c0d0086"
}

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

{
  "type": "max-message-queue-size-exceeded",
  "description": "The SMS queue for your account is full and cannot accept more messages right now. Your allowed rate is 60 messages per minute. The capacity of this queue is 900 messages (15 minutes). Reduce your message sending rate, or contact support to increase your allowed rate."
}