From twilio-developer-kit
Debug Twilio integrations and set up production observability. Covers the Console Debugger, Monitor Alerts API, Event Streams for error log streaming, status callback tracking, common error codes, and a systematic debugging workflow. Use this skill whenever a Twilio integration produces errors, messages fail to deliver, calls drop unexpectedly, or you need to set up monitoring for a production deployment.
npx claudepluginhub twilio/ai --plugin twilio-developer-kitThis skill uses the workspace's default tool permissions.
Twilio provides several layers of debugging and observability: the Console Debugger for interactive troubleshooting, the Monitor REST API for programmatic alert queries, Event Streams for real-time error streaming, and status callbacks for per-resource delivery tracking. This skill covers the systematic approach to diagnosing issues and setting up production monitoring.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Twilio provides several layers of debugging and observability: the Console Debugger for interactive troubleshooting, the Monitor REST API for programmatic alert queries, Event Streams for real-time error streaming, and status callbacks for per-resource delivery tracking. This skill covers the systematic approach to diagnosing issues and setting up production monitoring.
TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN -- see twilio-iam-auth-setuppip install twilio requests / npm install twilioCheck for recent errors on your account using the Monitor Alerts API.
Python
import os
from twilio.rest import Client
client = Client(os.environ["TWILIO_ACCOUNT_SID"], os.environ["TWILIO_AUTH_TOKEN"])
alerts = client.monitor.alerts.list(log_level="error", limit=10)
for alert in alerts:
print(f"{alert.date_created}: [{alert.error_code}] {alert.alert_text}")
Node.js
const twilio = require("twilio");
const client = twilio(process.env.TWILIO_ACCOUNT_SID, process.env.TWILIO_AUTH_TOKEN);
const alerts = await client.monitor.alerts.list({ logLevel: "error", limit: 10 });
alerts.forEach(a => {
console.log(`${a.dateCreated}: [${a.errorCode}] ${a.alertText}`);
});
When something fails, work through these layers in order:
1. Check status callbacks FIRST
(Did your endpoint receive delivery/call status? What error code?)
|
2. Check the resource directly via REST API
(GET /Messages/{sid} or /Calls/{sid} — current state + error_code)
|
3. Check number reputation / sender registration
(Is the number spam-flagged? Is A2P 10DLC registered? Toll-free verified?)
|
4. Check the Console Debugger for webhook/TwiML errors
(Console > Monitor > Errors — shows HTTP request/response details)
|
5. Check your webhook endpoint
(Is it reachable? Responding within 15s? Returning valid TwiML/200?)
|
6. Query Monitor Alerts API or Event Streams
(For patterns across many messages/calls, or historical analysis)
Why status callbacks first: Status callbacks tell you the exact error code for the specific message or call that failed. The Console Debugger aggregates errors across your account and may not surface the one you're looking for. Start specific, then broaden.
Number reputation checklist:
twilio-numbers-senders)Rule of thumb: If status callbacks show delivered but the user says they didn't receive it, the issue is on the carrier/device side (not Twilio). If the Console Debugger shows no errors at all, the problem is in your application (webhook, TwiML, business logic).
The Console Debugger shows errors and warnings for your account in real time.
Each entry includes:
Configure a Debugger webhook for real-time alerting:
Console > Monitor > Logs > Debugger > (gear icon) > set Callback URL
Debugger webhook POST parameters:
| Parameter | Description |
|---|---|
Sid | Debugger event identifier |
AccountSid | Account that generated the event |
Level | Error or Warning |
Timestamp | ISO 8601 time |
Payload | JSON: resource_sid, error_code, more_info, webhook (full request/response) |
Python (Flask) -- debugger webhook handler
import json, os
from flask import Flask, request
from twilio.request_validator import RequestValidator
app = Flask(__name__)
validator = RequestValidator(os.environ["TWILIO_AUTH_TOKEN"])
@app.route("/debugger", methods=["POST"])
def debugger_event():
sig = request.headers.get("X-Twilio-Signature", "")
if not validator.validate(request.url, request.form, sig):
return "Forbidden", 403
level = request.form.get("Level")
payload = json.loads(request.form.get("Payload", "{}"))
error_code = payload.get("error_code")
resource_sid = payload.get("resource_sid")
msg = payload.get("more_info", {}).get("msg", "")
print(f"[{level}] Error {error_code} on {resource_sid}: {msg}")
return "", 204
Node.js (Express) -- debugger webhook handler
const express = require("express");
const twilio = require("twilio");
const app = express();
app.use(express.urlencoded({ extended: false }));
app.post("/debugger", (req, res) => {
const valid = twilio.validateRequest(
process.env.TWILIO_AUTH_TOKEN,
req.headers["x-twilio-signature"],
`https://${req.headers.host}${req.originalUrl}`,
req.body
);
if (!valid) return res.status(403).send("Forbidden");
const payload = JSON.parse(req.body.Payload || "{}");
const { error_code, resource_sid } = payload;
const msg = payload.more_info?.msg || "";
console.log(`[${req.body.Level}] Error ${error_code} on ${resource_sid}: ${msg}`);
res.sendStatus(204);
});
The Monitor REST API (monitor.twilio.com/v1/Alerts) provides programmatic access to error and warning logs. Individual alert instances include the full HTTP request and response data.
Python -- query alerts with date filtering
from datetime import datetime, timedelta
# Alerts from the last 24 hours
start = datetime.utcnow() - timedelta(days=1)
alerts = client.monitor.alerts.list(
start_date=start,
log_level="error",
limit=50
)
for alert in alerts:
print(f"{alert.date_created} [{alert.error_code}]")
# Fetch full details including HTTP request/response
detail = client.monitor.alerts(alert.sid).fetch()
print(f" Request URL: {detail.request_url}")
print(f" Response body: {detail.response_body}")
Node.js -- query alerts with date filtering
const startDate = new Date(Date.now() - 24 * 60 * 60 * 1000);
const alerts = await client.monitor.alerts.list({
startDate,
logLevel: "error",
limit: 50,
});
for (const alert of alerts) {
console.log(`${alert.dateCreated} [${alert.errorCode}]`);
const detail = await client.monitor.alerts(alert.sid).fetch();
console.log(` Request URL: ${detail.requestUrl}`);
console.log(` Response body: ${detail.responseBody}`);
}
Retention: Enterprise accounts: 13 months. Free accounts: 30 days.
The Events resource (monitor.twilio.com/v1/Events) tracks all changes to Twilio resources -- phone number provisioning, account settings, recording access, API key creation, and more.
Python -- audit recent account changes
events = client.monitor.events.list(limit=20)
for event in events:
print(f"{event.event_date}: {event.event_type}")
print(f" Resource: {event.resource_type} ({event.resource_sid})")
print(f" Actor: {event.actor_type} ({event.actor_sid}) from {event.source_ip_address}")
Each event captures: event type, resource, actor (who triggered it), source (API / Console / Twilio admin), and IP address.
Use cases:
For production monitoring, stream errors to your infrastructure in real time using Event Streams. The Twilio SDK does not wrap Event Streams -- use requests / fetch directly.
Python -- set up error log streaming to a webhook
import os, requests
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
# Step 1: Create a webhook sink
sink = requests.post(
"https://events.twilio.com/v1/Sinks",
auth=(account_sid, auth_token),
data={
"Description": "Error monitoring sink",
"SinkType": "webhook",
"SinkConfiguration": '{"destination": "https://yourapp.com/twilio-errors", "method": "POST"}'
}
).json()
# Step 2: Subscribe to error log events
subscription = requests.post(
"https://events.twilio.com/v1/Subscriptions",
auth=(account_sid, auth_token),
data={
"Description": "Error log subscription",
"SinkSid": sink["sid"],
"Types": '[{"type": "com.twilio.error-logs.error.logged"}]'
}
).json()
print(f"Sink: {sink['sid']}, Subscription: {subscription['sid']}")
Sink types: webhook, kinesis, segment
Useful event types for observability:
| Event type | Description |
|---|---|
com.twilio.error-logs.error.logged | All errors and warnings on account |
com.twilio.messaging.message.delivered | Message delivered successfully |
com.twilio.messaging.message.undelivered | Message delivery failed |
com.twilio.voice.insights.call-summary | Post-call quality and status summary |
Status callbacks are the most granular observability mechanism -- they fire for individual resource state changes.
Message delivery tracking:
# Attach when sending
message = client.messages.create(
to="+15558675310", from_="+15017122661", body="Hello!",
status_callback="https://yourapp.com/msg-status"
)
Call lifecycle tracking:
call = client.calls.create(
to="+15558675310", from_="+15017122661",
url="https://yourapp.com/voice",
status_callback="https://yourapp.com/call-status",
status_callback_event=["initiated", "ringing", "answered", "completed"]
)
Recording completion tracking:
# In TwiML
response = VoiceResponse()
response.record(
recording_status_callback="https://yourapp.com/recording-status",
recording_status_callback_event="completed absent failed"
)
Recording status values: in-progress, completed, absent, failed. The RecordingUrl is available when status is completed.
When Twilio can't reach your webhook or receives an error, the problem is often in your infrastructure.
Common causes and fixes:
| Symptom | Likely cause | Fix |
|---|---|---|
| Error 11200 in Debugger | Webhook URL returned non-200 / unreachable | Verify endpoint is live: curl -I https://yourapp.com/sms |
| Error 11205 | HTTP connection failure (port closed, refused, firewall) | Verify server is running and port is open: curl -I https://yourapp.com/sms |
| Error 12100 | TwiML document could not be parsed | Check for debug output, BOM characters, or malformed XML |
| Parameters missing after redirect | HTTP 301/302 strips POST body | Fix URL to avoid redirect (add/remove www., use HTTPS directly) |
| Webhook works locally but not deployed | Tunnel expired or firewall | Use curl from an external host to test |
| Intermittent failures | ngrok session expired / recycled | Deploy to a stable host for anything beyond quick tests |
Test webhooks manually:
# Simulate an inbound SMS webhook
curl -X POST https://yourapp.com/sms \
-d "From=+15551234567" \
-d "To=+15559876543" \
-d "Body=Test message" \
-d "MessageSid=SM00000000000000000000000000000000"
Browser testing: Visit your webhook URL in Firefox -- it highlights XML errors in the response.
| Code | Name | Cause | Fix |
|---|---|---|---|
| 11200 | HTTP retrieval failure | Twilio cannot reach your webhook URL | Check URL, DNS, firewall, SSL cert |
| 11205 | HTTP connection failure | Webhook endpoint refused connection | Verify server is running and port is open |
| 11751 | Media download failure | MMS media URL unreachable | Check media URL accessibility |
| 12100 | Document parse failure | TwiML is not valid XML | Validate XML; remove debug output |
| 12200 | Schema compliance failure | TwiML verbs/attributes are invalid | Check TwiML reference for correct syntax |
| 20003 | Authentication error | Invalid Account SID or Auth Token | Verify credentials in environment |
| 21211 | Invalid To number | Number not in E.164 format | Use + country code + number |
| 21608 | Unverified number (trial) | Trial accounts can only send to verified numbers | Verify number or upgrade account |
| 30003 | Unreachable destination | Carrier cannot deliver message | Check number validity; retry later |
| 30006 | Landline or unreachable | Destination is a landline | Use voice channel instead |
| 30007 | Carrier filtering | Message filtered by carrier | Review content; register for A2P 10DLC |
| 30008 | Unknown error | Carrier returned generic error | Retry; contact support if persistent |
Full error reference: https://www.twilio.com/docs/api/errors
When you need the current state of a message or call (not waiting for a callback):
Python
# Check message delivery status
message = client.messages("SMxxxxxxxxxx").fetch()
print(f"Status: {message.status}, Error: {message.error_code}")
# Check call status
call = client.calls("CAxxxxxxxxxx").fetch()
print(f"Status: {call.status}, Duration: {call.duration}")
Node.js
const message = await client.messages("SMxxxxxxxxxx").fetch();
console.log(`Status: ${message.status}, Error: ${message.errorCode}`);
const call = await client.calls("CAxxxxxxxxxx").fetch();
console.log(`Status: ${call.status}, Duration: ${call.duration}`);
The Twilio CLI supports debug logging:
# Verbose output for any CLI command
twilio api:core:messages:list --limit 5 -l debug
# Log levels: debug, info, warn, error
Debug output goes to stderr, so you can pipe normal output while still seeing diagnostics.
Set up before going to production:
| What to monitor | How | Alert threshold |
|---|---|---|
| Webhook errors | Debugger webhook or Event Streams (com.twilio.error-logs.error.logged) | Any error |
| Message delivery failures | Status callback failed/undelivered | > 2% failure rate |
| Call completion rate | Status callback completed vs total | < 95% completion |
| Webhook response time | Your APM (DataDog, New Relic) | p95 > 5 seconds |
| 429 rate limit hits | Count in your backoff handler | > 5% of requests |
| Account configuration changes | Monitor Events API | Any unexpected change |
| Recording failures | Recording status callback failed/absent | Any failure |
twilio-webhook-architecturetwilio-reliability-patternstwilio-compliance-traffictwilio-iam-auth-setup