REST API: Best Practices

Please review our Security and Webhooks Security guides for requirements for encrypted communication including HTTPS/TLS, certificates, cipher suites, and request validation.

All Twilio customers are unique. There is no one size fits all recommendation to meet every imaginable use case. However, if you will be using the REST API for either a master or/and a subaccount, we recommend the use of API Keys. API Keys can be easily issued and revoked, providing easy control of an account's security.

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

If you are performing a large amount of GET requests, consider implementing webhooks aka StatusCallBack requests for the resource endpoint(s) your account is utilizing. The information contained in the responses posted to your servers will often remove the need to perform any future polling GET requests.

If you are frequently fetching the same data from Twilio, we recommend moving the data from Twilio to your servers. Once data has been successfully moved, delete data stored on Twilio servers if you no longer need it. Not only will this reduce costs, but this is also a generally recommended business practice for privacy, security, and compliance.

Almost all of our products have rate limits to ensure that all customers experience a high level of performance when using our platform. Please review the specific product API documentation to find the rate limits.

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

For API requests to Twilio: There are times when you may have a significant increase in usage. These may be due to marketing campaigns, business news, etc. Your account might receive API responses indicating you have exceeded concurrency limits for your account. If you receive 429 responses, those requests are never processed and are always safe to retry. Please see our article on 429 responses for more details.

For Twilio API responses to your servers: You may need to implement retries on callbacks as your servers may be under heavy load. For guidance, please review Webhooks: Connection Overrides .

Twilio strongly encourages all developers to monitor API response headers, in particular these two:

1
Twilio-Concurrent-Requests: 1
2
Twilio-Request-Duration: 0.111

Twilio-Concurrent-Requests indicates the number of concurrent requests, at that moment, for the account. Subaccount requests do not roll up into master account requests. The concurrency count includes requests that receive a 429 response.

Twilio-Request-Duration is the time it took for the request to be completed within the Twilio platform. This is the period between when the request hit our edge and when the response was sent back to your server. This does not include the network time between Twilio servers and your servers.

The more concurrent requests, or requests per second you have, the more likely you are to receive a 429 error from certain endpoints. If you think that you may have a spike in traffic (lots of requests over a short time) or that you will have sustained high traffic with the Twilio API, consider employing strategies to temporarily slow your requests down.

You can read the headers we return to manage this in an automated way. See above for strategies like avoiding unnecessary fetching and retries with exponential backoff.

We also encourage users to subscribe to our status page to be made aware of any incidents.

• Consider implementing the Account Debugger Webhook to send any warnings or errors directly to your servers.

• In the SDK usage guides (found in the left-hand navigation bar under each SDK) Twilio provides instructions for debugging, exception handling, and returning header information. The headers delivered in a Twilio API response not only return the number of concurrent requests on the account, and the duration of the specific request, but also the Unique Request ID, helpful when escalating an issue to support.

  Copy code block

  1
  Twilio-Request-Id: RQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  2
  

• If errors from an SDK are being returned, Twilio recommends testing the same API request either with Twilio CLI or curl. If successful results are returned from curl or from twilio, chances are the error is with the API request in the SDK code. If the errors are reproducible, please open a support request.

To ensure your account has the most up-to-date features and bug fixes we recommend updating your SDKs at least once a quarter.

Do you have a favorite best practice you'd like to see added to our list? Please let us know!

Let's build something amazing.