# 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](#sms-out-spec-errors) | The API response | HTTP status codes, such as `400`, `401`, `415`, and `429`. |
| [Message processing status and codes](#callback-error-codes-http) | The message status callback | `status` and `code_id`. |
| [Delivery receipt status values](#outbound-sms-dlr-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](https://jsonapi.org/format/#errors) with the
`title`, `detail`, `code`, and `status` fields.

*400 Bad Request*

Returned when the request payload does not follow [JSON:API](https://jsonapi.org/format/) or the [request
attributes](outbound-sms-api-reference.html#outbound-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}
```


*401 Unauthorized*

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](outbound-sms-api-reference.html#sms-out-spec-authentication).

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


*415 Unsupported Media Type*

Returned when the `Content-Type` header is not
`application/vnd.api+json`. See [Request headers](outbound-sms-api-reference.html#sms-out-spec-authentication).

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


*429 Too Many Requests*

Returned when the request rate exceeds the [rate limit](outbound-sms-api-reference.html#sms-out-spec-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](status-callbacks-and-delivery-receipts.html#outbound-sms-callback-delivery).

## 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](../../logs-analytics/sms-logs/outbound-logs.html#outbound-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**.

## Related resources

- [Status callbacks and delivery receipts](status-callbacks-and-delivery-receipts.html) - Review the callback payloads
  and the callback retry schedule.
- [Outbound SMS API reference](outbound-sms-api-reference.html) - Review authentication, endpoints, and
  request attributes.
- [HTTP OUT trunk settings reference](../sms-trunks/http-out/http-out-trunk-settings-reference.html) - Review
  the Source Address Settings and allowed IP addresses.
- [Sender ID Verifications](../sender-id-verifications/index.html) - Resolve Sender ID Verification
  errors such as `code_id` `10` and `11`.