Skip to main content

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.

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.

​
Error Code Mapping

The following table shows how common Telnyx error scenarios are mapped to Chirp error codes.
ScenarioChirp CodeHTTPDescription
Invalid destination numberinvalid_phone_number400The destination phone number is not valid or cannot receive SMS.
Number not assignedphone_number_not_assigned400The sending phone number is not assigned to your app.
Media too largemedia_too_large400The MMS media attachment exceeds the 5 MB size limit.
Carrier rejectedmessage_undeliverable402The carrier rejected the message (spam filter, invalid route, etc.).
Destination unreachablemessage_undeliverable402The recipient’s phone is unreachable or the number is disconnected.
Telnyx API errortelnyx_api_error424An unexpected error occurred with the Telnyx API.
Telnyx service downtelnyx_api_unavailable424Telnyx API is temporarily unavailable.
Rate limitedrate_limit_exceeded429Too 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:
SMS delivery failure
{
  "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
Invalid destination
{
  "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) 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 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.
SMS failure webhook
{
  "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"
      }
    }
  }
}
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.

​
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 to track delivery status in real time