API best practices

• Use HTTPS/TLS connection for all communications with the Twilio API. For development and testing, you can use HTTP for callbacks.
• Use certificates from a Certificate Authority (CA), such as Let's Encrypt. Twilio doesn't support self-signed certificates.
• Use TLS cipher suites to encrypt data in transit. Check TLS cipher suites for TwiML requests and status callbacks.
• Enable SSL certificate validation for webhooks in the Twilio Console, on the General Settings page.

For more information, see Security and Webhooks security.

To authenticate requests to the Twilio APIs, Twilio supports HTTP Basic authentication. Use your API key and secret as your credentials. When a key is compromised or no longer used, revoke it to prevent unauthorized access.

Note: If your application receives incoming webhooks from Twilio and you validate the signature on those incoming requests, use your Account SID and Auth Token for signature validation.

Learn more about Twilio API authentication.

• If you make frequent GET requests for the same resource, consider using webhooks for the resource instead. Webhooks allow Twilio to send updates to your servers when a resource changes, so you can avoid polling the API and reduce your request volume.
• If you often retrieve the same data from Twilio, consider moving that data to your own servers and deleting it from Twilio when no longer needed. This helps reduce costs and supports privacy, security, and compliance best practices.

Review the rate limits for the Twilio products you use. Most Twilio products have rate limits to ensure fair usage and quality experience for all customers using the Twilio platform.

To ensure deliverability during usage spikes, we recommend implementing retries with exponential backoff.

• For API requests to Twilio: During periods of high usage (such as marketing campaigns or business events), you might exceed your account's concurrency limits and receive a 429 Too Many Requests response. This means that the request wasn't processed and you can safely retry. Learn more about 429 Too Many Requests.
• For Twilio API responses to your servers: If your servers are under high load, you might need to implement retries on callbacks. Learn more about Webhooks: Connection Overrides.

Monitor the following API response headers to understand your account's usage and performance:

• Twilio-Concurrent-Requests: The current number of concurrent requests for your account. Subaccount requests don't roll up to the primary account. This count includes requests that receive a 429 Too Many Requests.
• Twilio-Request-Duration: The time it took for the request to be completed within the Twilio platform. This measures the period from when the request reached Twilio's edge to when the response was sent back to your server. It doesn't include the network time between Twilio servers and your servers.

The more concurrent requests or requests per second you send, the more likely you're to receive a 429 Too Many Requests response from certain endpoints. If you expect a spike in traffic or sustained high usage, consider slowing down your requests temporarily.

Subscribe to the Twilio status page for any ongoing incidents that might affect your API requests.

• Check the Twilio API responses for headers that can help you debug issues. When you need to contact Twilio Support, provide the unique request ID from the Twilio-Request-Id header.
• Use the Debugging webhook to send warnings or errors directly to your servers.
• If you encounter SDK errors, test the same API request with curl. If the request succeeds with curl, the issue is likely in your SDK code. If the error persists with both methods, contact Support.
• Update your SDKs at least once a quarter to ensure you have the latest features and bug fixes.