SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Requirements for Connecting to the Twilio REST API and Troubleshooting Common Issues

All connections to the Twilio infrastructure have the same connectivity requirements, regardless of the product used or the subdomain being accessed. This guide covers helpful information for configuring your environment to connect to the Twilio REST API and troubleshooting common issues.

Notice: Be sure to check Twilio’s status page for any current issues.

Connection Requirements

HTTPS: All traffic to the REST API uses HTTPS on standard port 443 and is accessible via any HTTP client, including web browsers.

Requirement: Firewalls and proxies must allow outbound HTTPS traffic on port 443 to connect to the REST API.

Tip: If your machine can browse https://api.twilio.com/, your network allows access.

IP Addresses: Twilio’s cloud infrastructure dynamically assigns IP addresses for the REST API from a large range of Amazon Web Services (AWS) IP addresses, and those IP addresses can change without advance notice.

Requirement: Firewalls and proxies must allow HTTPS traffic to any public IP address or, or allow Twilio’s subdomains (e.g. api.twilio.com).

Tip: Be sure your DNS cache respects Twilio’s TTL of 60 seconds to avoid making requests to stale IP addresses.

TLS Versions and Cipher Suites: Twilio’s REST API currently supports only TLS v1.2. Support for earlier versions was removed in June 2019. For more details, please see Twilio REST API’s TLS and Cipher Suite Security Changes for June 2019.

Requirement: HTTP clients must negotiate a supported TLS version and cipher suite.

Tip: Full details of TLS versions and cipher suites currently supported by the Twilio REST API are available from SSL Labs.

Certificate Chain: To establish a secure connection, HTTP clients must verify our certificate chain and root authority. Industry trusted root certificates are automatically bundled with most HTTP client software packages and normally require no additional configuration.

The full certificate chain and root authority can be seen by clicking the Security icon in a browser:

Requirement: HTTP clients must have Twilio’s root certificate installed in their local trust store.

Tip: For manual installations, download the latest Mozilla-trusted certificate bundle.

Caution: We do not recommend pinning certificates, as this can cause your application to break if our certificates change in the future. See also: Monitoring Updates to Twilio REST API Security Settings.

Custom REST Client: If your network requires use of a proxy server to connect to the public internet or has other custom connectivity requirements, you can create a custom REST client and pass it into the Twilio helper library to meet your specific needs:

Troubleshooting Common Issues

When troubleshooting REST API connection issues, there are several different error signatures, causes, and solutions to consider.

Tip: See our Resources for Diagnosing Connection Issues to Twilio’s REST API for diagnostic tools and utilities.

Connection Timeouts: Timeout with Twilio Error Code 20500

Requests that successfully connect to Twilio’s REST API but aren’t able to complete in a timely fashion will timeout from Twilio’s side at 26 seconds and return an HTTP 500 status code with Twilio error code 20500.

  • Possible Causes:
    • Paging through large data sets with PageSize=1000
    • Searching large lists by FriendlyName
        
  • Possible Solutions:
    • Set PageSize=50
    • Search by SID instead of FriendlyName
    • Save Twilio log data to your own database for querying

Tip: If you see Error 20500 frequently and there are no issues on our status page, please contact Twilio Customer Support to investigate.

Timeout with HTTP Response, but No Twilio Error Code: Requests that timeout and return an HTTP response without a Twilio-specific error code in the body most likely encountered an issue with a local network element (e.g. corporate proxy) before reaching the public internet.

  • Possible Causes
    • Web proxy blocking traffic (4xx status code)
    • Web proxy timing out sooner than Twilio’s timeout (5xx status code)
        
  • Possible Solutions
    • Ensure web proxies are configured to allow HTTPS traffic to Twilio
    • Configure web proxy credentials and connection requirements in your HTTP client (Example: Custom client in Twilio helper library for Java)
    • Try connecting from a different network to isolate the issue

Timeout with No HTTP Response: Requests that timeout with no HTTP response are due to local networking or ISP connectivity issues.

  • Possible Causes
    • No internet connection
    • Firewall blocking HTTPS traffic
    • Web proxy not configured
    • DNS resolution failing
        
  • Possible Solutions
    • Check that the client has access to the public internet
    • Ensure firewalls and web proxies allow HTTPS traffic to Twilio
    • Verify DNS provider and ISP respect Twilio’s TTL setting (60 seconds)
    • Try connecting from a different network or machine to isolate the issue

SSL/TLS Errors

Chain Issues: Client errors describing a certificate chain issue, such as “Unable to find valid certification path to requested target,” typically indicate Twilio’s root certificate is not available locally to verify the remote certificate as trusted.

  • Possible Causes
    • Twilio’s root certificate is not installed in the local trust store
    • Client is referencing the wrong path to the local trust store
        
  • Possible Solutions
    • Install the standard Mozilla certificate bundle in the local trust store
    • Verify the client is referencing the correct path to the local trust store

Caution: We do not recommend pinning certificates, as this can cause your application to break if our certificates change in the future. See also: Monitoring Updates to Twilio REST API Security Settings.

Danger: Do not disable certificate validation in your HTTP client, as it could allow your requests to connect to a malicious third-party.

Handshake Failure: SSL/TLS handshake failures typically indicate the client does not support the TLS version or cipher suites required by the REST API.

Tip: Enable SSL/TLS debugging in your HTTP client, if available, to get low level details of failures. Example for Java: Debugging SSL/TLS Connections.

Domain Name Mismatch: A domain name mismatch error means the certificate presented by the remote host did not match the domain name that was requested.

  • Possible Causes
    • Stale DNS entry retained a previous Twilio IP address now reassigned to a non-Twilio host
    • Web proxy interfering with request routing
    • Malicious party attempting a man-in-the-middle attack
        
  • Possible Solutions
    • Clear local network DNS cache
    • Verify DNS provider and ISP respect Twilio’s TTL setting (60 seconds)
    • Ensure web proxy is routing requests correctly to Twilio
    • Try connecting from a different network to isolate the issue

Danger: Do not disable certificate validation in your HTTP client, as it could allow your requests to connect to a malicious third-party.

Twilio Customer Support

For additional assistance in troubleshooting connection issues to our REST API, please contact Twilio Customer Support.

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk