Rate this page:

Debugging Your Twilio Application

Integrating Twilio products into your software is easy, but as you are building and testing your application you may run into issues you did not anticipate. Here are some tips that we have found useful.

Break the Problem Down

The first thing to do is break the problem down into smaller parts. For instance, if you are using the REST API to make an outbound phone call, there are several things taking place:

  • Your code uses a helper library to invoke Twilio's REST API
  • The HTTP request is authenticated and parameters validated
  • An outbound phone call is placed
  • Once the call is answered an HTTP request made to the webhook you specified
  • The TwiML returned from the webhook is parsed and executed

Any one of those steps could experience an issue, whether it's a network issue or invalid TwiML being executed. If possible, test each of these steps independently to better isolate the issue.

Debugging Webhooks

If you're experiencing an issue with a webhook that you've configured, there are several things you can do to track down the source of the issue.

Check the Error Logs

First, check out the Error logs. When Twilio runs into a problem with your webhook, it will log information about this in the Error logs. The Error logs flag these debugging events as either errors or warnings. Warnings mean that Twilio encountered an issue but was still able to process the request. An error is more severe and means that Twilio was not able to process the request at all. When you review these debugging events, you'll have access to:

  • The exact error or warning that occurred
  • Possible causes for this error
  • Suggested solutions
  • The entire HTTP request and response associated with this webhook request

Run the Webhook in Your Browser

Remember, you're just writing a web application. There's nothing Twilio does that you can't test right there in your browser. Visit the URLs in your web browser, and see that you don't have any errors.

  • Firefox treats XML files really nicely, highlighting any invalid XML in your document.
  • Mimic Twilio's data passing by manually adding data to your URLs. For example, if you ask Twilio to digits and the action is, you can open your browser to to verify what happens if the user presses 1.
  • Make sure your application isn't sending debug output, because that will nearly always cause problems. You can, however, wrap any such output in XML comment blocks... they're the same as HTML comment blocks: <!-- COMMENTS HERE -->

Check for HTTP Redirects

Twilio is a well-behaved HTTP client, so when it receives an HTTP 301 or 302 redirect it will follow it to the specified URL. However, on the subsequent request the original parameters are not included. Occasionally you may see parameters such as Digits or RecordingUrl not arriving where you expect them. In this case, check to make sure the URL is not returning a redirect.

As an example, when a request is made to the action URL, a Digits parameter is included in the POST request. If the action URL redirects to another URL, Twilio will follow the redirect and issue a GET request to the specified URL. This GET request will include the standard set of parameters included with every Twilio request, but will not include the additional Digits parameter.

Common situations that may return unexpected redirects are:

  • A server that automatically redirects all HTTP requests to HTTPS
  • A URL rewriting rule that rewrites request URLs to include or exclude www.

To see what your server is returning to Twilio, create a test request using cURL, Postman or your HTTP client of choice and inspect the response returned from your URL.

Debugging Calls to the REST API

While errors and warnings related to Twilio invoking your webhooks are available in the the Error logs, the REST API will synchronously return an error object to your application in the event an error takes place. The error object will contain the HTTP response status code, Twilio-specific error code, error message, and a link to the Error Code Reference.

  "code": 21211,
  "message": "The 'To' number 5551234567 is not a valid phone number.",
  "more_info": "",
  "status": 400

Try Making the Call in the API Explorer

A great tool to use when debugging issues with the REST API is the Console's API Explorer. The API Explorer is a web-based tool that makes it easy to execute real calls against the REST API and examine the output. Use this tool to simulate the call that your application is making and compare its output to the output from your app.

Stream Error Logs to Amazon Kinesis

Twilio Event Streams is an API that allows you to subscribe to a unified stream of interactions across different Twilio products. You can stream your data to your existing systems by configuring a streaming technology like Amazon Kinesis, or a webhook. Error Log events will be generated on Event Streams for all errors and warnings on your Twilio applications. Learn more about the events here.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Community Forums or browsing the Twilio tag on Stack Overflow.


        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more