> ## Documentation Index
> Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS Error Codes

> Understanding SMS and MMS delivery error codes

When sending SMS/MMS messages through Chirp, delivery failures from Telnyx are mapped to Chirp's standard error format. The original Telnyx error details are preserved in the `provider` object for debugging.

For a general overview of the error format, see [Errors](/api_reference/errors).

## Error Code Mapping

The following table shows how common Telnyx error scenarios are mapped to Chirp error codes.

| Scenario                   | Chirp Code                  | HTTP | Description                                                          |
| -------------------------- | --------------------------- | ---- | -------------------------------------------------------------------- |
| Invalid destination number | `invalid_phone_number`      | 400  | The destination phone number is not valid or cannot receive SMS.     |
| Number not assigned        | `phone_number_not_assigned` | 400  | The sending phone number is not assigned to your app.                |
| Media too large            | `media_too_large`           | 400  | The MMS media attachment exceeds the 5 MB size limit.                |
| Carrier rejected           | `message_undeliverable`     | 402  | The carrier rejected the message (spam filter, invalid route, etc.). |
| Destination unreachable    | `message_undeliverable`     | 402  | The recipient's phone is unreachable or the number is disconnected.  |
| Telnyx API error           | `telnyx_api_error`          | 424  | An unexpected error occurred with the Telnyx API.                    |
| Telnyx service down        | `telnyx_api_unavailable`    | 424  | Telnyx API is temporarily unavailable.                               |
| Rate limited               | `rate_limit_exceeded`       | 429  | Too many requests sent in a short period.                            |

## Example Error Response

When an SMS fails to send, you receive a standard Chirp error response with the Telnyx error details in the `provider` object:

```json icon="code" title="SMS delivery failure" theme={null}
{
  "error": {
    "type": "provider_error",
    "code": "message_undeliverable",
    "message": "The message could not be delivered. The carrier rejected the message.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#message_undeliverable",
    "provider": {
      "source": "telnyx",
      "code": "40300",
      "message": "Carrier rejected the message"
    }
  }
}
```

## Common Delivery Failures

### Invalid Destination Number

The destination phone number is not valid. This can happen when the number is formatted incorrectly, does not exist, or is a type that cannot receive SMS (e.g., some toll-free numbers or short codes).

**How to fix:**

* Verify the phone number is in E.164 format (e.g., `+14155552671`)
* Confirm the number is a mobile phone that can receive SMS
* Remove any spaces, dashes, or parentheses from the number

```json icon="code" title="Invalid destination" theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_phone_number",
    "message": "The phone number \"+1555\" is not a valid destination for SMS.",
    "doc_url": "https://docs.buildwithchirp.com/api_reference/error-codes#invalid_phone_number",
    "param": "to[0]"
  }
}
```

### Carrier Rejected

The recipient's carrier rejected the message. This typically happens due to spam filtering, content restrictions, or carrier-level blocking.

**Common reasons:**

* Message content triggered a spam filter
* The sender number is not properly registered for A2P (Application-to-Person) messaging
* The carrier blocks messages from certain number types
* The recipient has opted out of receiving messages from this number

**How to fix:**

* Review your message content for spam trigger words
* Ensure your sending number has a proper messaging profile configured
* Register your brand and campaign with [The Campaign Registry (TCR)](https://www.campaignregistry.com/) for 10DLC numbers
* Check if the recipient has opted out

### Rate Limited

You are sending messages too quickly. Telnyx and carriers enforce rate limits to prevent abuse.

**How to fix:**

* Implement a sending queue with rate limiting
* Spread messages over a longer time period
* Use the `Retry-After` response header to determine when to retry
* See [Rate Limits](/api_reference/rate-limits) for Chirp API rate limits

## Webhook Delivery Failures

When an SMS fails to deliver after being accepted, Chirp sends a webhook notification with the failure details.

```json icon="code" title="SMS failure webhook" theme={null}
{
  "event": "messages.sms.failed",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "message": {
      "id": "msg_abc123",
      "from": "+15551234567",
      "to": "+15559876543",
      "type": "SMS"
    },
    "app": {
      "id": "app_xyz"
    },
    "error": {
      "type": "provider_error",
      "code": "message_undeliverable",
      "message": "The carrier rejected the message.",
      "provider": {
        "source": "telnyx",
        "code": "40300",
        "message": "Carrier rejected the message"
      }
    }
  }
}
```

<Info>
  Webhook delivery failures happen asynchronously. The initial API call may return a success response (message queued), but the delivery can still fail later. Always set up webhooks to track delivery status.
</Info>

## Troubleshooting

If you are experiencing persistent SMS delivery issues:

1. **Check your messaging profile** -- Ensure your Telnyx messaging profile is properly configured with the correct webhook URL
2. **Verify 10DLC registration** -- For US numbers, ensure you have completed A2P 10DLC registration through TCR
3. **Test with different carriers** -- Try sending to numbers on different carriers to isolate carrier-specific issues
4. **Review message content** -- Some content may trigger carrier spam filters
5. **Check number capabilities** -- Confirm your sending number supports SMS/MMS
6. **Monitor webhook events** -- Set up [webhooks](/sms/webhooks-setup) to track delivery status in real time