Diagnosing Twilio Programmable SMS Error 30004: Carrier‑Blocked Messages

Recognizable condition

When you send a message via Twilio Programmable SMS, the API returns a status of failed and the response includes error_code: 30004. This error indicates that the downstream carrier blocked the message before it reached the recipient.

Cause / diagnostic table

Possible cause	What to look for in Twilio Console / logs
Recipient number not in E.164 format or inactive	Log shows error_message mentioning "invalid" or "unreachable" number.
Carrier spam filter triggered by content	Log includes carrier feedback such as "SPAM" or "filtered" alongside 30004.
Sender Twilio number not A2P‑enabled	Log shows no carrier feedback but the Messaging Service or Sender ID is flagged as "not registered for A2P".
Account exceeded daily messaging rate limit	Log shows error_code: 30004 with error_message referencing "rate limit" or "quota exceeded".

Ordered checks

1. Verify the 'To' number format and status
   • Where: Twilio Console → Phone Numbers → Verify or via E.164 validation tool.
   • Permission: Ability to view phone numbers (standard account access).
   • Check: Confirm the number starts with a "+" and country code, and that it is active (you can place a test call).
2. Inspect the specific message log for error details
   • Where: Twilio Console → Messaging → Logs → filter by error_code = 30004.
   • Permission: Read access to Messaging Logs.
   • Check: Note any carrier feedback message and the timestamp.
3. Review message body for prohibited content
   • Where: Same log entry; copy the body field.
   • Permission: Read access to logs.
   • Check: Look for URLs, excessive length (>160 characters for GSM‑7), or known spam keywords (e.g., "free", "win").
4. Confirm the sending number is A2P‑enabled and linked to a Messaging Service
   • Where: Phone Numbers → select the sender → check "A2P" flag; Messaging Services → Service → Sender Pool.
   • Permission: Manage Phone Numbers and Messaging Services.
   • Check: The number shows "A2P capable" and is assigned to a Service with a valid Messaging Service SID.
5. Review account usage for rate‑limit breaches
   • Where: Dashboard → Usage → Usage Records → filter by "Messages Sent".
   • Permission: View Usage.
   • Check: Compare current day's count against your account's daily limit.

Fixes tied to findings

Check outcome	Corrective action
To number malformed or inactive	Correct the number to proper E.164 format or obtain an active number; resend.
Log shows carrier feedback indicating spam	Modify message content (remove URLs, shorten, avoid spammy terms) or switch to a verified A2P sender; resend.
Sender number lacks A2P registration	Complete Trust Hub registration for A2P on that number, or replace the sender with a number that already has A2P enabled.
Account exceeded daily limit	Implement client‑side throttling (e.g., delay between requests) or upgrade to a higher‑throughput plan; then resend.

Escalation criteria

• After correcting number format and content, the same error_code: 30004 persists for three or more consecutive attempts.
• Carrier feedback in the log indicates a network‑level block that requires whitelisting (e.g., "carrier block – please contact Twilio Support").
• Account‑level limits are reached despite proper throttling, suggesting a need for a higher throughput contract.

When any of the above occurs, open a support ticket via the Twilio Console → Support → Create Ticket, providing the Message SID, timestamps, and the relevant log excerpt.

Verification steps (after applying a fix)

1. Send a test message to a known‑good, verified A2P‑enabled number (e.g., your own mobile) with simple body "Hello". Use the Twilio CLI (run in a terminal where twilio is installed and TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN are set as environment variables):

   twilio api:core:messages:create \
     --to "+15551234567" \
     --from "+15005550006" \
     --body "Hello"

   Where: Local development machine or CI runner with CLI access. Permission: Account SID/Auth Token with messages:create scope. Expected check: The command returns a Message SID; no error is printed.
2. In the Twilio Console, locate the newly created Message SID under Messaging → Logs and confirm that status progresses to queued then delivered and that error_code is absent.
3. Optionally, retrieve the message via the Helper Library (e.g., Python) and assert that message.error_code is None:

   from twilio.rest import Client
   client = Client()
   msg = client.messages("SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx").fetch()
   assert msg.error_code is None
   assert msg.error_message is None

   Where: Any environment with the Twilio Helper Library installed.
4. Monitor the Messaging > Logs dashboard for a 15‑minute window after the corrective action; ensure no new entries with error_code: 30004 appear for the same sender/recipient pair.

Limitations

• This guide assumes you have access to the Twilio Console and the ability to send API requests; it does not cover carrier‑specific whitelisting processes that must be handled by Twilio Support.
• International number formatting beyond basic E.164 validation (e.g., handling of local dialing prefixes) is not detailed; refer to each country’s numbering plan if you encounter persistent format issues.
• The guide does not address media (MMS) errors; error code 30004 for MMS may have additional causes such as unsupported media types.