Troubleshooting
This guide shows you how to troubleshoot common Twilio Communications API issues. It explains where error information appears, how to interpret it, and what to do next.
Where to find errors
Errors can appear in three main places:
- API responses
- Twilio Console
- Event logs
API responses
If a request fails, the API returns a 4xx or 5xx error in the response body.
400errors indicate that your request is invalid. The response includes a message that explains the problem.500errors indicate an internal Twilio error.
If you need help with a 400 or 500 error, contact comms-api@twilio.com.
For a complete list of error codes and descriptions, see the API errors documentation.
Twilio Console
Use the Console Debugger to find errors related to message delivery, opt-outs, and other post-request issues.
Event logs
Twilio Event Streams deliver real-time events to webhooks and other destinations, such as AWS Kinesis and Segment. You can subscribe to the event types you need. If an event fails to deliver, Twilio queues the event and retries when the destination becomes available.
Twilio Communications API event types
You can subscribe to these Communications API-specific event types:
Operations
com.twilio.comms-api.operation.processingcom.twilio.comms-api.operation.completed
Messages
com.twilio.comms-api.message.queuedcom.twilio.comms-api.message.sentcom.twilio.comms-api.message.failedcom.twilio.comms-api.message.deliveredcom.twilio.comms-api.message.undeliveredcom.twilio.comms-api.message.read
You can also use events from downstream services, such as Programmable Messaging. These events include SM/MM SIDs for individual message deliveries.
See the outbound Messaging delivery status events for more details:
com.twilio.messaging.message.deliveredcom.twilio.messaging.message.failedcom.twilio.messaging.message.queuedcom.twilio.messaging.message.readcom.twilio.messaging.message.sentcom.twilio.messaging.message.undelivered
For error logging, subscribe to the error-logs event type:
com.twilio.error-logs.error.logged
