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

The Twilio REST API is an HTTP-based API accessed via product-specific subdomains:

  • api.twilio.com
  • lookups.twilio.com
  • chat.twilio.com
  • video.twilio.com
  • … and many more

But regardless of the product being used and the subdomain being accessed, the connections are made to the same Twilio infrastructure and have the same connectivity requirements.

Use this guide when configuring your environment to connect to the Twilio REST API and troubleshooting common issues.

Tip: 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 whitelist based on 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 TLS v1.0, v1.1 and v1.2 and many different cipher suites, however, we will be making changes to both TLS and cipher suite support in the future.

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

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.

Possible Causes
  • Client does not support correct TLS version
  • Client does not support available cipher suites
Possible Solutions

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
Powered by Zendesk