Twilio error 30008 means the message failed and the carrier chain didn't say why. It's the catch-all for "undelivered, reason unknown", so the code itself won't tell you the cause. You find the cause by looking at the pattern around it.

That makes it a frustrating one. There's no single fix, but there is a fast way to narrow it down.

What 30008 really means

When a message fails, the destination carrier normally returns a specific reason: the number is unreachable, the handset is off, the message was filtered. Sometimes the carrier returns a failure with no usable detail, or a detail the provider can't map to a known code. The provider reports that as 30008, "Unknown error".

So 30008 is not a diagnosis. It's an absence of one. Treat it as a prompt to compare the failed messages against the delivered ones.

Likely causes

Possible causeClue in your data
Handset or carrier problem on the recipient sideOne recipient, one carrier, intermittent
Landline or non-text-capable numberThe same numbers fail every time
Carrier filtering without a specific codeContent or sender pattern in common
Reassigned or deactivated numberOld contacts fail, recent ones pass
Temporary carrier outageMany unrelated recipients fail in one window
Sender registration issueFailures start after a registration change

A triage checklist

  1. Look for a pattern before you look for a cause. Group the 30008s by recipient carrier, sender number, time of day and message body. A pattern is usually visible within a few dozen messages.
  2. Check whether it's one recipient. If it's a single contact, test the number. A bad or reassigned number is the most common culprit. How to check whether a number can receive texts lays out the steps.
  3. Check whether it's one sender. If every failure comes from the same number, look at its registration and reputation. Our post on texts not sending from business numbers covers that.
  4. Check the time window. A cluster of failures in a short window across many recipients points to a carrier or provider incident. Check the provider's status page.
  5. Compare content. Send a plain, short copy of a failed message to your own test handsets. If it passes, the original was probably filtered.
  6. Retry once, with a delay. For a likely transient cause, one retry after a few minutes is reasonable. Reuse the same idempotency key so it can't double send.
  7. Stop at a limit. If it fails a second time, quit retrying and flag the contact for review.

For a broader retry design, SMS API retries and failure handling covers backoff and limits.

Don't hide it from the user

If you build a product on top of messaging, an unknown error is still something your customer sees. "Failed, reason unknown" with no next step creates a support ticket. Give a plain status and a suggested action, such as checking the number, and log the rest. Delivery status UI for end users has patterns for that.

When to worry

One stray 30008 in a thousand sends is normal background noise. Carriers drop messages for reasons nobody reports. Start investigating when the rate climbs, when it clusters on one sender or one carrier, or when the same recipients fail twice. A steady rise is a signal worth an alert, even if each individual failure looks harmless.

Log enough to debug it later

Because the code is vague, the surrounding data is what you'll rely on. For every failed message, keep:

  • The message ID and your own internal reference
  • The sender number and the recipient
  • The timestamp and the final status
  • The error code, exactly as returned
  • Which template or campaign produced it

With those fields you can group failures after the fact, which is how you find the pattern in step 1. See SMS observability, logging and alerting for what to alert on.

How this shows up on Ready

Ready removes some failures before they can turn into an unknown error. Opt-outs and numbers on your Ban list are refused up front and not charged, and a number Ready's own sends have already seen as a landline is refused up front too. That means a chunk of the usual 30008 suspects never reach a carrier.

What's left is the honest unknowns: a handset problem, a carrier hiccup, a filter that gave no reason. For those, the same triage applies. Check the sender's registration with GET /v1/registration, check the number with GET /v1/validate/:phone, and use an Idempotency-Key on any retry:

POST /v1/messages
X-API-Key: <key>
Idempotency-Key: 0b8e41c7-6a3d-4f12-8e5b-91c2d7a4f360

{"to": "+12125550142", "body": "Your appointment is tomorrow at 10 AM.", "consent_attested": true}

Ready's error responses are documented at https://docs.tryready.com/api/errors, and number validation is at https://docs.tryready.com/api/validate-numbers.

The short version

Error 30008 is an unknown delivery failure, so the fix is detective work and not a single setting. Group failures by recipient, sender, time and content, rule out bad numbers and registration problems, retry once with a delay, and log enough to see the pattern next time. For the wider set of codes, read SMS error codes explained and SMS API error codes and troubleshooting.