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

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.

Parameters

Parameter Type Description
type string The Type of error.
description string A detailed description of why the error occurred
fieldErrors array List of errors in fields
fieldErrors.fieldName string Name of field with error
fieldErrors.description string Description of the error

Example: Invalid telephone numbers

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"
}

Responds

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.

Parameters

Value Description Example
timestamp Time error Occurred 2019-07-29T17:21:43.751+0000
status HTTP Status 401
error Description of error Unauthorized
message Any more information Bad credentials
path API Path /api/v2/users//messages

Example: Incorrect credentials sent

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"
}

Responds

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.

Parameters

Value Description Example
timestamp Time error Occurred 2019-07-29T17:21:43.751+0000
status HTTP Status 403
error Description of error Forbidden
message Any more information Access is denied
path API Path /api/v2/users//messages

Example: User does not have access

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"
}

Responds

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.

Path nonexistent Error Schema

Value Description Example
timestamp Time error Occurred 2019-07-29T17:21:43.751+0000
status HTTP Status 404
error Description of error Not found
message Any more information no message found
path Path that wasn't found /happy

Example: Path does not exist

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"
}

Responds

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.

Parameters

Parameter Type Description
type string Type of Error
description string A detailed description of why the error occurred

Example: Incorrect content-type sent

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"
}

Responds

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.

Parameters

Parameter Type Description
type string The Type of error.
description string A detailed description of why the error occurred
fieldErrors array List of errors in fields
fieldErrors.fieldName string Name of field with error
fieldErrors.description string Description of the error

Example: Too many requests

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"
}

Responds

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."
}

results matching ""

    No results matching ""