Connecting Twilio to Text only takes a minute. Once you're set up, you can send and receive SMS directly from your inbox. And if anything gets in the way, we’re here to help you through it.
How to deal with temporary errors
Temporary errors mean the message couldn't be delivered right now, but the issue is likely to resolve on its own. In most cases, retrying after a short delay is enough, though the right approach varies by error type.
Error | Code | What it means | What to do |
Recipient unreachable | 30003 | The recipient's device is off, out of coverage, or otherwise unavailable. | Retry after 30–60 minutes. If it persists, the number may be inactive. |
Carrier queue overflow | 30001 | The carrier's message queue is temporarily at capacity. | Retry after a short time and increase the delay with each failed attempt. |
Carrier rejected the message | 30008 | The carrier rejected the message for an unspecified reason, often due to temporary filtering or routing issues. | Retry after a few minutes. If it fails repeatedly, check your message content against carrier guidelines. |
Rate limited | 20429 | You've exceeded Twilio's sending limits for your account or number. | Slow down your send rate. Review your throughput limits and consider spreading traffic across multiple numbers or using a messaging service. |
How to handle fatal errors
Unlike temporary errors, fatal errors won't resolve on their own. They indicate a fundamental problem with your account or credentials that blocks all sending and receiving until actively fixed.
Error | Code | What it means | What to do |
|---|---|---|---|
Account not active | 10001 | Your Twilio account exists but is not active — it may be pending activation, disabled, or closed. | Log in to your Twilio Console to confirm your account status. If the account is new, complete any pending activation steps. If it was previously working, contact Twilio Support to identify what changed. |
Invalid credentials or suspended account | 20003 | Twilio rejected the request because your API credentials are invalid, or your account has been suspended. | Check that your Account SID and Auth Token in your Text settings match what's in your Twilio Console. If credentials are correct, log in to Twilio directly to check your account status — suspension is usually due to a billing issue or a policy violation. |
While a fatal error is active, all Twilio messaging is paused — you won’t be able to send or receive SMS through Text until the underlying issue in Twilio is resolved. Once your account is restored, reconnect the integration in your Text settings to resume.
How to fix the blocking error: Region not enabled
If you're seeing a blocking error [code 21408], it means you're trying to send an SMS to a country that isn't enabled in your Twilio account's SMS Geo Permissions.
Twilio restricts outbound messaging by region to help protect accounts from SMS Traffic Pumping Fraud. By default, new accounts can only send messages to the home country verified during signup. You can expand or restrict this at any time through the Twilio Console.
Each country has its own SMS regulations, which may vary depending on sender type and use case. Review the SMS Guidelines for a country before enabling its permissions.
Only users with the Account Owner or Account Admin role can modify SMS Geo Permissions. Changes take effect immediately - disabling a region will stop SMS delivery to that destination right away.
To update SMS Geo Permissions:
Open the Twilio Console and go to Messaging in the left sidebar under the Develop section.
Click Settings, then Geo Permissions.
Find the country you want to enable or disable — use the Filter by Country search or scroll through the list.
Check the box next to the country to enable it, or uncheck it to disable.
Click Save geo permissions and confirm in the dialog that appears.
When the update is saved successfully, a confirmation banner — Messaging geo permissions updated successfully - appears in the top right corner.
Enabling High Risk countries
Some countries are flagged as High Risk due to elevated rates of SMS Traffic Pumping Fraud. Twilio continuously monitors and updates these designations as conditions change. To see more details about why a country is flagged, click the warning indicator next to its name.
Enabling a High Risk country follows the same steps as above, but you'll be prompted with an additional confirmation dialog acknowledging the risk. After enabling, it's recommended to:
To further protect against SMS fraud:
Preventing Messaging Fraud — an overview of fraud types and Twilio's built-in safeguards.
SMS Pumping Protection — enable automatic detection and blocking of pumping attempts on Programmable Messaging.
Verify — add phone verification flows to confirm users are real before sending messages.
Verify Fraud Guard — automatically blocks high-risk traffic within your Verify workflows.
Anti-Fraud Developer's Guide — a technical reference for building fraud-resistant messaging into your application.
How to handle context-limited errors
Context-limited errors mean the message was blocked based on its content or delivery context — not a problem with your account. Retrying the same message won't work; the fix requires reviewing and adjusting what you're sending.
Error | Code | What it means | What to do |
|---|---|---|---|
Message blocked | 30004 | The carrier blocked the message, typically due to content that violates messaging policies — such as prohibited topics, flagged keywords, or missing opt-in compliance. | Review your message content against Twilio's Messaging Policy and your target carrier's guidelines. Common triggers include certain URLs, promotional language, or messages sent to numbers without proper opt-in records. |
Frequently asked questions
Account SID and Auth Token are asked for when setting up Twilio in Text
Twilio can suspend an account for two broad reasons: a billing issue (the account balance hit zero) or a violation of Twilio's Acceptable Use Policy
You can check your current throughput allocation in the Twilio Console under Messaging → Services, or refer to Twilio's Rate Limits and Message Queues documentation for a full breakdown by number type.