Twilio Error Handling: Common Errors, Retries, and Debugging Guide

import os
import time
from twilio.rest import Client
from twilio.base.exceptions import TwilioRestException

client = Client(
    os.environ["TWILIO_ACCOUNT_SID"],
    os.environ["TWILIO_AUTH_TOKEN"]
)

def send_message_with_retry(to_number, body, max_retries=3):
    last_error = None
    for attempt in range(max_retries):
        try:
            message = client.messages.create(
                body=body,
                from_=os.environ["TWILIO_PHONE_NUMBER"],
                to=to_number
            )
            print(f"Sent: {message.sid} (attempt {attempt+1})")
            return message

        except TwilioRestException as e:
            last_error = e
            print(f"Attempt {attempt+1} failed:")
            print(f"  Code: {e.code}")
            print(f"  Status: {e.status}")
            print(f"  Message: {e.msg}")

            if e.code in [20003, 20012, 20429, 21610]:
                # Retryable errors
                wait = 2 ** attempt  # Exponential backoff: 1, 2, 4
                print(f"  Retrying in {wait}s...")
                time.sleep(wait)
            else:
                # Non-retryable, fail immediately
                print("  Fatal error, not retrying")
                raise

    print(f"Failed after {max_retries} attempts")
    return None

# send_message_with_retry("+14155551234", "Hello!")

# Most frequent Twilio error codes
error_codes = {
    20001: "Account not ready for this action",
    20003: "Authentication failure - check Account SID and Auth Token",
    20012: "Account suspended or closed",
    20429: "Rate limit exceeded - slow down requests",
    21211: "Invalid 'To' phone number format",
    21212: "Invalid 'From' phone number - call from an owned number",
    21214: "Message body is required",
    21401: "Invalid 'From' number - messaging service not configured",
    21408: "Permission not enabled for this country",
    21602: "Message body too long (>1600 chars)",
    21610: "Unreachable carrier - phone cannot receive SMS",
    21611: "Message has been blocked by carrier",
    21612: "Landline or unreachable carrier",
    30001: "Queue overflow - too many messages",
    30002: "Account message limit exceeded",
    30003: "Too many messages to a single number",
    63018: "WhatsApp template not approved",
}

def get_error_advice(error_code):
    advice = error_codes.get(error_code, "Unknown error - check Twilio docs")
    retryable = error_code in [20429, 21610, 30001, 30002, 30003]
    print(f"Error {error_code}: {advice}")
    print(f"Retryable: {retryable}")
    return advice

# get_error_advice(20429)
# Expected output:
# Error 20429: Rate limit exceeded - slow down requests
# Retryable: True

import time
from threading import Lock

class TwilioRateLimiter:
    """Simple rate limiter for Twilio API calls."""

    def __init__(self, max_per_second=50):
        self.max_per_second = max_per_second
        self.tokens = max_per_second
        self.lock = Lock()
        self.last_refill = time.time()

    def _refill(self):
        now = time.time()
        elapsed = now - self.last_refill
        self.tokens = min(self.max_per_second,
                          self.tokens + elapsed * self.max_per_second)
        self.last_refill = now

    def acquire(self):
        while True:
            with self.lock:
                self._refill()
                if self.tokens >= 1:
                    self.tokens -= 1
                    return
            time.sleep(0.01)

limiter = TwilioRateLimiter(max_per_second=50)

def rate_limited_send(to_number, body):
    limiter.acquire()
    return client.messages.create(
        body=body,
        from_=os.environ["TWILIO_PHONE_NUMBER"],
        to=to_number
    )

# Test: send 10 messages quickly
# for i in range(10):
#     rate_limited_send("+14155551234", f"Test message {i+1}")

from flask import Flask, request, Response
from twilio.twiml.messaging_response import MessagingResponse

app = Flask(__name__)

@app.route("/sms/status", methods=["POST"])
def handle_status_callback():
    """Handle delivery status updates and errors."""
    message_sid = request.form.get("MessageSid")
    message_status = request.form.get("MessageStatus")
    error_code = request.form.get("ErrorCode", "0")
    error_message = request.form.get("ErrorMessage", "")

    print(f"Status: {message_sid} -> {message_status}")

    if error_code and error_code != "0":
        print(f"ERROR {error_code}: {error_message}")
        # Log to monitoring system
        log_error(message_sid, error_code, error_message)

        # Trigger retry for specific errors
        if error_code in ["21610", "21611", "30003"]:
            retry_with_different_number(message_sid)

    return Response("", status=200)

def log_error(message_sid, error_code, error_message):
    print(f"[ERROR LOG] {message_sid}: {error_code} - {error_message}")

def retry_with_different_number(message_sid):
    print(f"Retrying {message_sid} with different sender...")
    # Implementation depends on your retry logic

# Programmatic access to Debugger events
def get_debugger_events(limit=10):
    """Fetch recent Twilio Debugger events."""
    events = client.monitor.events.list(
        limit=limit,
        source_ip="*"
    )
    print(f"Recent debugger events ({len(events)}):")
    for event in events:
        print(f"  [{event.date_created}] {event.description}")
        print(f"    SID: {event.sid}")
        print(f"    Level: {event.level}")
    return events

# get_debugger_events()
# Expected output:
# Recent debugger events (3):
#   [2026-06-28 10:30:00] Error 21610 - Unreachable carrier
#     SID: AExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
#     Level: ERROR
#   [2026-06-28 10:25:00] Warning - SMS to landline
#     SID: AEyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy
#     Level: WARNING