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 sentProblemFixed
(212) 555-0199Brackets, spaces and dash+12125550199
212-555-0199No country code+12125550199
2125550199No plus, no country code+12125550199
+1 212 555 0199 ext 4Extension in the field+12125550199
+112125550199Country code repeated+12125550199
+1212555019Nine digits, one shortAsk for the number again
0121 555 0199Local trunk prefix keptDrop the leading zero, add country code
+1 (555) 010-0123Not a real, routable US numberValidate 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

  1. Print the exact string you sent. Read it character by character, not from your UI. Invisible whitespace and non-breaking spaces are common.
  2. Strip everything but digits and a leading plus. Remove spaces, dashes, brackets, dots and extension text.
  3. 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.
  4. Drop trunk prefixes. Many countries write a leading zero locally that doesn't belong in E.164.
  5. Check the length. A US number is 11 digits after the plus, counting the leading 1.
  6. Validate before you store. Use a phone number library and a lookup, not a regular expression alone.
  7. 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.