Twilio error 21211 means the number in the To field isn't a valid phone number the provider can route to. Nine times out of ten it's a formatting problem: a missing plus sign, a missing country code, stray characters, or a number with the wrong number of digits.
It's one of the easiest errors to fix and one of the easiest to prevent, because it's raised before any carrier is involved. Nothing is delivered and there's nothing to retry until the number is corrected.
What E.164 is
E.164 is the international phone number format. It starts with a plus sign, then the country code, then the subscriber number, with no spaces, dashes or brackets. A US number looks like +12125550199: plus, then 1 for the US, then ten digits.
Most messaging APIs want this format, and it's the safest one to store. Store it once, in one shape, and you avoid a whole class of bugs.
Common mistakes behind 21211
| What you sent | Problem | Fixed |
|---|---|---|
(212) 555-0199 | Brackets, spaces and dash | +12125550199 |
212-555-0199 | No country code | +12125550199 |
2125550199 | No plus, no country code | +12125550199 |
+1 212 555 0199 ext 4 | Extension in the field | +12125550199 |
+112125550199 | Country code repeated | +12125550199 |
+1212555019 | Nine digits, one short | Ask for the number again |
0121 555 0199 | Local trunk prefix kept | Drop the leading zero, add country code |
+1 (555) 010-0123 | Not a real, routable US number | Validate before sending |
The last row catches people out. A number can be perfectly formatted and still be invalid, because the area code or exchange doesn't exist. Formatting is necessary, and it isn't sufficient.
A checklist to fix it
- Print the exact string you sent. Read it character by character, not from your UI. Invisible whitespace and non-breaking spaces are common.
- Strip everything but digits and a leading plus. Remove spaces, dashes, brackets, dots and extension text.
- Add the country code. If you only handle one country, add it for numbers without one. If you handle many, don't guess. Ask for the country at capture time.
- Drop trunk prefixes. Many countries write a leading zero locally that doesn't belong in E.164.
- Check the length. A US number is 11 digits after the plus, counting the leading 1.
- Validate before you store. Use a phone number library and a lookup, not a regular expression alone.
- Normalize at the edge. Do it once, when the number enters your system, so every send reads clean data. The post on E.164 formatting for SMS APIs has code for this.
Formatting is not validity
Once the number is formatted, you still want to know whether it can receive a text. A formatted number can be a landline, disconnected or never assigned. Checking whether a phone number is real and the guide to a phone number validation API explain the difference and the order to do things in.
Where bad numbers come from
Knowing the source helps you fix it once instead of patching each send. Typical entry points are web forms with free-text phone fields, CSV imports from spreadsheets, CRM syncs that carry formatting from another system, and copy-pasted numbers with hidden characters. Spreadsheets are a quiet offender: they drop leading zeros and turn long numbers into scientific notation.
Fix the entry point. Use a phone input that asks for the country, normalize on save, and reject what can't be parsed with a message the person can act on. Then the send path only ever sees clean numbers.
How this shows up on Ready
On Ready, the to field in POST /v1/messages is E.164. A 10-digit US number is treated as +1, which forgives the most common formatting gap, but anything else should arrive in full E.164 form. Normalize at capture time and you won't depend on that.
A correct request looks like this:
POST /v1/messages
X-API-Key: <key>
Idempotency-Key: c41d9e07-5b2a-4d6f-a7c3-0e8b19f2d5a6
{"to": "+12125550199", "body": "Your order #1042 has shipped.", "consent_attested": true} To check a number before you send, call GET /v1/validate/:phone. Ready also refuses some sends up front without charging for them, such as opt-outs and numbers on your Ban list, so a refusal isn't always a formatting problem. Read the response before you assume it is. The validation endpoint is documented at https://docs.tryready.com/api/validate-numbers, the send endpoint at https://docs.tryready.com/api/messages, and error responses at https://docs.tryready.com/api/errors.
For bulk sends, the same rule applies to every entry in the to list on POST /v1/messages/bulk. Clean the list first. One malformed entry in a large import is easier to catch before the job starts than after. Our post on bulk chunking and partial failures shows how to handle a list that has a few bad rows.
The short version
Error 21211 is a bad To number, usually a formatting slip. Normalize to E.164 once at the edge, check the length, validate before you send, and don't retry the same string. For related codes, see SMS error codes explained and SMS API error codes and troubleshooting.