Twilio breaking changes, updated weekly

Every verified Twilio trap in Footgun: changes and behaviors that break code or give wrong results, newest first. Each one has the error you see, the fix, and the date it was last checked. The list updates when the weekly check adds or retires a trap. For the full cause and sources, open the trap, or see all Twilio traps.

1. fg-0159· added 2026-10-15· last checked 2026-10-15

   Error 21608 still blocks unverified recipients after you upgrade the Twilio account

   Symptom

   21608 Upgrade and create an approved primary compliance profile to reach unverified numbers

   Fix

   On trial, verify each recipient. On a paid account, submit the primary compliance profile in Trust Hub and wait for approval; verified caller IDs are only a testing stopgap.

2. fg-0162· added 2026-10-15· last checked 2026-10-15

   One emoji or curly quote doubles the number of SMS segments you pay for

   Symptom

   num_segments is 2 for a message well under 160 characters

   Fix

   Normalize quotes and dashes before sending, avoid emoji in bulk sends, or turn on Smart Encoding in the Messaging Service. Check numSegments on the returned message.

3. fg-0163· added 2026-10-15· last checked 2026-10-15

   SMS from a US local number fails with error 30034 until A2P 10DLC registration is approved

   Symptom

   30034 US A2P 10DLC - Message from an Unregistered Number

   Fix

   Finish Brand and Campaign registration, add the number to the Messaging Service linked to the Campaign, and send through that service. Use a toll-free number, short code or Verify while registration is pending.

4. fg-0164· added 2026-10-15· last checked 2026-10-15

   Toll-free number messages to US and Canada fail with error 30032 until verification is approved

   Symptom

   30032 Toll-Free Number Has Not Been Verified

   Fix

   Submit Toll-Free Verification in the Console or through the Messaging Compliance API and wait for approval before sending. A rejected request can be edited and resubmitted for seven days.

5. fg-0165· added 2026-10-15· last checked 2026-10-15

   Twilio client throws 'accountSid must start with AC' when created with an API key

   Symptom

   Error: accountSid must start with AC

   Fix

   Pass the key SID and secret as the first two arguments and the real account SID in the options object.

6. fg-0166· added 2026-10-15· last checked 2026-10-15

   Twilio trial accounts will not send your own SMS text; Body must be a template name such as sms_2fa

   Symptom

   Quickstart send code with a custom Body fails on a new trial account

   Fix

   During the trial pass a template name as body, or upgrade the account before testing real copy.

7. fg-0167· added 2026-10-15· last checked 2026-10-15

   validateRequest returns false behind a proxy, tunnel or load balancer although the Auth Token is right

   Symptom

   Signature check passes locally but fails for every request in production

   Fix

   Build the validation URL from your configured public base URL, not from the incoming Host header. For application/json requests use validateRequestWithBody with the raw body.

8. fg-0168· added 2026-10-15· last checked 2026-10-15

   Verify check returns 404 'was not found' when the code was already approved or has expired

   Symptom

   HTTP 404 from verificationChecks.create with a valid Service SID

   Fix

   Treat a 404 from a check as used or expired, and start a new verification. Do not check twice on retry.

9. fg-0160· added 2026-10-15· last checked 2026-10-15

   Error 21610 after a recipient texts STOP, and the API cannot override it

   Symptom

   21610 Attempt to send to unsubscribed recipient

   Fix

   Catch 21610, record the contact as opted out, and stop retrying. Only the recipient can lift it by texting START.

10. fg-0169· added 2026-10-15· last checked 2026-10-15

    Verify sends fail with 60203 'Max send attempts reached' while testing with one phone number

    Symptom

    60203 Max send attempts reached

    Fix

    Complete the lifecycle with a check, or cancel the verification in tests, or wait 10 minutes for it to expire.

11. fg-0083· added 2026-10-14· last checked 2026-10-14

    People who text your Twilio number get a reply that says 'Accepted'

    Symptom

    Sender gets a reply containing Accepted or another raw response body

    Fix

    Respond to the webhook at once with an empty TwiML document and do the processing after that.

12. fg-0084· added 2026-10-07· last checked 2026-10-07

    Twilio restricted API key fails with error 8021 although Read is granted

    Symptom

    Error 8021

    Fix

    Tick List as well as Read for each resource the key must enumerate.