Best practices for avoiding rate limiting

If you make a lot of API requests in a short amount of time, you may bump into the API rate limit for requests. When you reach the limit, the Zendesk API stops processing any more requests until a certain amount of time has passed.

The rate limits for a Zendesk Support account are as follows:

Plan	Requests per minute
Essential	10
Team	200
Professional	400
Enterprise	700
High Volume API Add-On (Professional or Enterprise)	2500

The Add-On increases a qualifying plan's limit to 2500 requests per minute. It doesn't add an additional 2500 requests to the plan's limit.

As well, each endpoint can have its own rate limit. For example, the rate limit for updating a ticket with a comment for a given agent is 15 updates within a 10-minute window.

This article covers the following best practices for avoiding rate limiting:

• Monitoring API activity against your rate limit
• Catching errors caused by rate limiting
• Reducing the number of API requests
• Regulating the request rate
• FAQ

Monitoring API activity against your rate limit

You can use the API dashboard in the Zendesk Support admin interface to monitor your API activity against your rate limit in the last 24 hours. See Tracking API activity against your rate limit in the Support Help Center.

You can also use the following response headers to confirm the account's current rate limit and monitor the number of requests remaining in the current minute:

X-Rate-Limit: 700
X-Rate-Limit-Remaining: 699

Note: These headers aren't available for Help Center API requests.

Catching errors caused by rate limiting

For each request, you can check to see if you've bumped into the rate limit. If you get a response code of 429, "Too Many Requests", you've hit the rate limit.

It's best practice to include code in your script that catches 429 responses. If your script ignores the "Too Many Requests" error and keeps trying to make requests, you might start getting null errors. At that point the error information won't be useful in diagnosing the problem.

For example, a curl request that bumps into the rate limit might return the following response:

< HTTP/1.1 429
< Server: nginx/1.4.2
< Date: Mon, 04 Nov 2013 00:18:27 GMT
< Content-Type: text/html; charset=utf-8
< Content-Length: 85
< Connection: keep-alive
< Status: 429
< Cache-Control: no-cache
< X-Zendesk-API-Version: v2
< Retry-After: 93
< X-Zendesk-Origin-Server: ****.****.***.*****.com
< X-Zendesk-User-Id: 338231444
< X-Zendesk-Request-Id: c773675d81590abad33i
<
* Connection #0 to host SUBDOMAIN.zendesk.com left intact
* Closing connection #0
* SSLv3, TLS alert, Client hello (1):
Rate limit for ticket updates exceeded, please wait before updating this ticket again

The response contains the following key information:

• Status: 429
• Retry-After: 93

The 429 status code means too many requests. The Retry-After header specifies that you can retry the API call in 93 seconds. Your code should stop making additional API requests until enough time has passed to retry.

The following pseudo-code shows a simple way to catch rate-limit errors:

response = request.get(url)
if response.status equals 429:
    alert('Rate limited. Waiting to retry…')
    wait(response.retry-after)
    retry(url)

Reducing the number of API requests

Make sure you make only the requests that you need. Here are areas to explore for reducing the number of requests:

1. Optimize your code to eliminate any unnecessary API calls.

   For example, are some requests getting data items that aren't used in your application? Are retrieved data items being put back to your Zendesk product instance with no changes made to them?

2. Cache frequently used data.

   You can cache data on the server or on the client using DOM storage. You can also save relatively static information in a database or serialize it in a file.

3. Sideload related data.

   You can avoid unneccesary API calls by sideloading one set of records with another. Sideloading lets you get two sets of records in a single request. See Sideloading related records.

4. Use bulk and batch endpoints such as Update Many Tickets, which lets you update up to 100 tickets with a single API request. See From 100 Requests to 1: Introducing Our New Bulk and Batch APIs on the Zengineering blog.

Regulating the request rate

If you regularly approach or bump into the rate limit, consider including a process in your code that regulates the rate of your requests so that they're distributed more evenly over time. This is known as a throttling process or a throttling controller. Regulating the request rate can be done statically or dynamically. For example, you can monitor your request rate and regulate requests when the rate approaches the rate limit.

To determine if you need to implement a throttling process, monitor your request errors. How often do you get 429 errors? Does the frequency warrant implementing a throttling process?

Frequently asked questions

• Is there an endpoint that returns all endpoints for a resource, including the different rate limits and times to retry?

  No, we don't provide a rate-limit endpoint.

  However, we do provide the following response headers that you can use to confirm the account's current rate limit and monitor the number of requests remaining in the current minute:

  X-Rate-Limit: 700
  X-Rate-Limit-Remaining: 699
  

• What happens when the rate limit is reached?

  The request isn't processed and a response is sent containing a 429 response code and a Retry-After header. The header specifies the time in seconds that you must wait before you can try the request again.

• Will batching calls reduce the number of API calls? How about making parallel calls?

  No, batching calls won't reduce the number of API calls.

  However, using a bulk or batch endpoint will reduce calls. See From 100 Requests to 1: Introducing Our New Bulk and Batch APIs on the Zendesk developer blog.