We can't wait to see what you build! And we'd like to encourage you to build it using these recommended best practices.
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.
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 posting 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 own servers. Once data has been successfully moved, delete data stored on Twilio servers if you no longer needed. Not only will this will reduce costs, this is also a generally recommended business practice for privacy, security, and compliance.
To delete data that Twilio is storing on your behalf, such as voice recordings for which you no longer have a business reason, delete these resources at non-peak hours and at a controlled rate. This will avoid competition with other timely requests your business is making to the Twilio API.
Almost all of our products have rate limits to ensure all customers experience high-performance on 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 429 Error Responses article.
For Twilio API Responses to your servers: You may need to implement retries on callbacks as your servers may be under heavy load, please review Webhooks Connection Overrides.
Twilio strongly encourages all developers to monitor API Response Headers. In particular these two:
Twilio-Concurrent-Requests: 1 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.
Twilio-Request-Duration is the time it took for the request to complete within the Twilio platform. This is the time the request hit our edge and until the time 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.
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 Usage Guides (found in the left-hand navigation bar under each Server-Side 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.
- If errors from a server-side SDK are being returned, Twilio recommends testing the same API request either with the twilio-cli or curl. If successful results are returned from curl or from the twilio-cli, 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? Let us know!
We can't wait to see what you build!