Troubleshooting Alerts, Debug Events, and Errors on Twilio Voice Calls – Twilio Support

This guide is intended to help troubleshoot any alerts, debug events, or errors on Twilio Programmable Voice calls. This guide covers the following topics for diagnosing and resolving your issues:

Check for Debug Events using one of the following methods:
Check for Twilio Incidents
Identify the Issue
Attempt to Replicate the Issue

Check for Debug Events via the Console Call Logs

Access the Call Logs page in Console.
Search for any calls flagged with a debug event - these will be highlighted in red.
Clicking on a red highlighted call log will display the Call SID, timestamp, and phone numbers, along with the Notification SID, error code, and error description message.
Scroll down the page to the Request Inspector to see the HTTP status code and response we received from your site.

No debug events are listed: If you don't see any debug events posted for the call in question, this indicates Twilio believes we have successfully executed the call, and the issue likely lies elsewhere. Continue troubleshooting with the following checklist:

Is an outbound call not connecting?
Is your TwiML URL or Application SID responding as intended?
Are you (or a caller) experiencing any audio quality issues?

A debug event is listed: If you do see a debug event listed, review the information provided for clues to resolving your issue. Additional information for this error can be found at https://www.twilio.com/docs/api/errors/XXXXX - just replace XXXXX with the error number flagged on your call. If you are unable to resolve your issue with the information provided, continue reading for additional troubleshooting.

Check for Debug Events via the Console Debugger

Access the Debugger page in Console.
Any debug events that have occurred over the selected time-frame will be listed.
Clicking on a debug event will display the Notification SID, Resource (Call) SID, and timestamp, along with the error code and a description of the problem.
Scroll down the page to the Request Inspector to see the HTTP status code and response we received from your site. Review this information for clues to resolving your issue.

No debug events are listed: If you don't see any debug events posted for the call in question, adjust the timeframe drop-down menu. If you continue to see no results, this indicates Twilio believes we have successfully executed the call, and the issue likely lies elsewhere. Continue troubleshooting with the following checklist:

Is an outbound call not connecting?
Is your TwiML URL or Application SID responding as intended?
Are you (or a caller) experiencing any audio quality issues?

A debug event is listed: If you do see a debug event listed, review the information provided for clues to resolving your issue. If you are unable to resolve your issue with the information provided, continue reading for additional troubleshooting.

Check for Debug Events via the REST API

Debug events can be found via the REST API by making an HTTP GET request to a specific call's Notifications sub-resource:

api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications.json

Here’s an example cURL script:

curl -G 'https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications.json' \
-u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'

This example will pull details for any debug events logged on a specific call SID. To make this script work for you, make the following updates, and then paste it into a terminal window:

Line 1 update with your Account SID and the Call SID
Line 2 update with your Account SID and Auth Token

A JSON response will be returned with details of any debug events flagged on your call. A call without any debug events will have a blank Notifications section. Here's an example of what a response might look like for a call with a debug event:

{
    "first_page_uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications.json?CallSid=CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&__referrer=runtime&Format=json&PageSize=50&Page=0",
    "end": 0,
    "previous_page_uri": null,
    "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications.json?CallSid=CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&__referrer=runtime&Format=json&PageSize=50&Page=0",
    "page_size": 50,
    "page": 0,
    "notifications": [
        {
            "sid": "NOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
            "log": "0",
            "error_code": "11202",
            "more_info": "https://www.twilio.com/docs/errors/11202",
            "message_text": "msg=An+attempt+to+retrieve+content+from+https%3A%2F%2Fwww.mysite.com%2Ftwilio+returned+the+HTTP+status+code+502&Msg=An+attempt+to+retrieve+content+from+https%3A%2F%2Fwww.mysite.com%2Ftwilio+returned+the+HTTP+status+code+502&sourceComponent=12000&ErrorCode=11202&httpResponse=502&url=https%3A%2F%2Fwww.mysite.com%2Ftwilio&LogLevel=ERROR",
            "message_date": "Thu, 18 Apr 2019 20:11:01 +0000",
            "request_method": "POST",
            "request_url": "https://www.mysite.com/twilio",
            "date_created": "Thu, 18 Apr 2019 20:11:01 +0000",
            "api_version": "2010-04-01",
            "date_updated": "Thu, 18 Apr 2019 20:11:01 +0000",
            "uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Notifications/NOXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
        }
    ],
    "next_page_uri": null,
    "start": 0
}

Is an outbound call not connecting?
Is your TwiML URL or Application SID responding as intended?
Are you (or a caller) experiencing any audio quality issues?

Check for Twilio Incidents

Check the Twilio Status Page to see if there is an active incident, or an incident during the timeframe you reported issues, that could be causing your issues. For full details, please see Checking Twilio Service and API Status with the Status Page.

No incidents are listed that may be affecting calls: If you don't see an incident posted that may affect calls, then there is likely an issue elsewhere. Continue reading for additional troubleshooting.

An incident may be affecting calls: If you see an incident posted that may affect incoming calls to your Twilio phone number, please monitor the status, and then test again once the incident is resolved.

Identify the Issue

Attempt to ascertain the full details surrounding this issue:

Is the issue affecting the call? How so?
Which side of the call is reporting the issue(s): caller, callee, or both?
Does this issue occur at the same time each call?
Does this issue only occur with specific phone numbers or number types (landline, mobile, VoIP, etc.)?
Does this issue only occur when calling or receiving calls from a specific region or country?
Do other callers/callees report similar issues?

Once you are able to answer these questions, continue reading for additional troubleshooting.

Attempt to Replicate the Issue

Attempt another test call or two between the same phone numbers, and then try using the same Twilio phone number with different caller/callee phone numbers. The goal is to determine if this was a one-off, if the issue is limited to specific phone numbers or service providers, or if there may be a larger issue that requires investigation.

Issue is always replicated: If you are able to replicate the issues on all calls in the same direction (to or from) with your Twilio phone number, we need to perform additional testing. Continue reading for additional troubleshooting.

Issue is sometimes replicated: If you are able to replicate issues only some of the time on calls in the same direction, check for any patterns:

If URLs from only specific server or host are unreachable or connect inconsistently, review your server logs or try escalating to your host.
If specific files used with the <Play> command are having trouble loading, verify they're reachable, and of a supported file type.
If no pattern can be found, collect additional examples, and then continue reading for additional troubleshooting.

Unable to replicate this issue: If you are unable to replicate the issues, it's unlikely we will be able to address this report. Continue to monitor, and restart troubleshooting as needed if additional reports are received.

Escalate to Twilio Support

If you can rule out all of the above issues, Twilio's Support team can help investigate what went wrong. Please collect 3 or more examples of calls to or from the same Twilio phone number that have reported similar issues from the last 24 hours, and include the following information:

Call SIDs
Twilio 5-digit Error codes
Description of how issues present themselves on calls
Variance of issues
Frequency of issues
Replication pattern

When you have collected this information, please share it with our Support team.