Outbound SMS errors and status codes#

Use this reference to look up the errors and status values of outbound SMS. The API returns HTTP errors immediately when it rejects a request. Processing results and delivery statuses arrive later in callbacks.

Result

Where it appears

Values

HTTP and API errors

The API response

HTTP status codes, such as 400, 401, 415, and 429.

Message processing status and codes

The message status callback

status and code_id.

Delivery receipt status values

The DLR event callback

status, such as DELIVERED.

HTTP and API errors#

If your API request is malformed or unauthorized, the API returns an immediate error response. Each error response contains an errors array in the JSON:API error format with the title, detail, code, and status fields.

Returned when the request payload does not follow JSON:API or the request attributes are invalid. For example, a required attribute is missing or empty, destination starts with +, a bulk request has more than 1000 numbers, or the request has neither source nor campaign_id. When the resource type is wrong, detail is type is invalid.

 1{
 2  "errors": [
 3    {
 4      "title": "Bad Request",
 5      "detail": "Invalid request",
 6      "code": "400",
 7      "status": "400"
 8    }
 9  ]
10}

Returned when the Authorization header is missing or invalid, or when the request comes from an IP address that the trunk does not allow. See Authentication.

 1{
 2  "errors": [
 3    {
 4      "title": "Unauthorized",
 5      "detail": "Authorization failed",
 6      "code": "401",
 7      "status": "401"
 8    }
 9  ]
10}

Returned when the Content-Type header is not application/vnd.api+json. See Request headers.

 1{
 2  "errors": [
 3    {
 4      "title": "Unsupported Media Type",
 5      "detail": "Unsupported Media Type",
 6      "code": "415",
 7      "status": "415"
 8    }
 9  ]
10}

Returned when the request rate exceeds the rate limit.

 1{
 2  "errors": [
 3    {
 4      "title": "Too many requests",
 5      "detail": "too many requests in a given amount of time",
 6      "code": "429",
 7      "status": "429"
 8    }
 9  ]
10}

Message processing status and codes#

The message status callback reports how DIDWW processed each message.

status

Description

Success

The message was sent successfully. code_id is null.

Routing error

DIDWW could not route the message, for example because the trunk cannot use the sender. The message is not sent, and fragments_sent and price are 0. code_id explains the reason.

Failed

The message failed. code_id explains the reason.

The code_id attribute provides specific details about a message failure.

code_id

Description

null

Message was sent successfully

1, 3

No routes found

2

No rate found

4, 6

Internal error

5

SMS trunk is blocked

7

Origination account is blocked

8

SMS source address is not allowed

9

SMS destination address is not allowed

10

Sender ID Verification not found

11

Sender ID Verification is blocked

100

No balance was available during the message’s TTL

101

All delivery attempts failed within the TTL

102

No encoding available

103

Max balance attempts reached

104

Message defragmentation failed

105

Routing failed

For the retry schedule of callbacks that your endpoint does not accept, see Delivery behavior and constraints.

Delivery receipt status values#

When DLR events are enabled, the DLR event callback reports the final delivery status from the carrier in its status attribute, for example:

status

Description

DELIVERED

The carrier reported that the message was delivered.

FAILED

The carrier reported that the message could not be delivered.

EXPIRED

The carrier reported that the message expired before delivery.

Outbound SMS logs#

The Outbound SMS logs show the Status and Reason of each sent message. The Reason describes the message’s code_id in words. For example, a message with code_id 8 has the Status ROUTING ERROR and the Reason SMS source address is not allowed.