Menu

Expand
Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: Best Practices

We can't wait to see what you build! And we'd like to encourage you to build it using these recommended best practices.

Control access to your accounts

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.

Avoid unnecessary fetching

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.

Know your limits

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.

Retries with Exponential Backoff

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.

Monitoring

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.

You can read the headers we return to manage this in an automated way. See above for strategies above 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.

Troubleshooting best practices

  • 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.
Twilio-Request-Id: RQXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
  • 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.

Keep your SDKs up to date

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

Did we miss something?

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!

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.