Best practices to avoid 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 outlined in Rate limits in the Support API docs. Get familiar with the limits before starting your project.
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:
-
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?
-
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.
-
Sideload related data.
You can avoid unnecessary 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.
-
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.
19 Comments
Hello, is the limit controlled by subdomain or by origin IP address? I am asking because I am planning to develop a system to make API requests on behalf of different zendesk subdomains. So the API requests would originate from the same IP address and I would like to know if I should expect problems with this.
**@Mayama:** The rate limits are on a subdomain basis not based on IP address.
Does the rate of 200 rpm also apply to the Sandbox instance of main Zendesk instance?
Yes Mihai, it does.
We're trying to add the "Help" knowledge base widget to our website but always see 429 too many requests. Could that be due to this?
Hi Darren. Just adding the web widget would typically not put you over the top of your API limits. I would also check for other integrations or apps that might be calling Zendesk APIs and look there.
If there's another script or web app that's making API calls, it could be putting you over your limit. If that's the case, then following the practices of this article may help.
If it's still not clear what may be putting you over your limit, then sending in a ticket to support@zendesk.com can get you more help specific to your environment. Hope this helps!
Are there any plans to revisit these limits? The user limit seems rather low.
We're on enterprise support and are limited to 700/minute when using auth tokens, but have an app that runs for the logged in user, which is getting throttled as it makes a large number of individual requests. It processes batches of tickets so there's no real way to limit this.
Hello Russell Dunn -- there have been no announced plans to change the current limits. There is the "High Volume API" add-on for situations where a higher rate limit is needed. Typically rate limit conversations are unique to particular needs and the discussion is directed to the account executive.
Depending on the use-case, sometimes there are alternative approaches that could avoid hitting a rate limit -- more details would be needed if you want to discuss that possibility (what the requests are, what the batches consist of, etc).
I would like to test that code that I am writing to handle the 429 response actually works. I guess the only way to test it would be to somehow send enough requests to run into the limit?
Hi Karen,
The easiest rate-limit to hit would likely be the Incremental Exports endpoints, as they're limited to 10 requests per minute.
Otherwise, rapid-fire updates to a single-ticket can do this pretty quickly as well (making a trigger that points to a target to update a specific ticket in a loop could hit this limit fast).
Hopefully that helps for your testing!
Hi
I can't seem to find any documentation regarding rate limits for anonymous requests via the requests end-point.
We're on an enterprise plan so should have 700/min limit (and the header response supports this) - however it seems we're getting a response of;
{"error":"APIRateLimitExceeded","description":"Rate limit for creating new tickets reached, please wait before submitting more tickets"}
Long before we hit this limit when using the requests endpoint. The header itself still indicates plenty of capacity (e.g. 698 of 700 left).
Any idea what's going on?
Cheers
Hi Jason Taylor
The rate-limit of 700/min is for authenticated requests to that endpoint. If you're hitting a much lower rate-limit, I suspect you may be running into the anonymous (un-authenticated) requests limit. Because this is a common vector for spammers to abuse our platform, we set a lower rate-limit for such anonymous requests based on the IP address from which they originate.
If this still doesn't explain what you're seeing, please reach out to our support team to take a closer look.
Hey Dwight
Thanks for the speedy reply. I figured that may be the case - and a totally understandable restriction! As a suggestion, it might be worth highlighting that there are lower limits for anonymous requests as it wasn't something that came up during our discovery phase unfortunately.
My follow on question from here is; what is the material difference when authenticating and creating new tickets via the requests end-point vs. the tickets end-point? Ideally we'd like to continue using requests as that is what we've built, but if there are significant benefits to using tickets then I would like to understand what they are.
J
HeyO Jason,
Definitely a good piece of feedback. I believe our Abuse team has tried to avoid publishing the specific limits for these anonymous requests to avoid broadcasting to spammers just how hard they can hit us, but calling out that "The limits for anonymous requests are substantially lower than those for authenticated requests" seems safe enough to me. I'll pass that along to our Docs team for review.
The largest differences between those two endpoints are these:
Please let me know if this helps to clear things up!
Yes, that really helped and has cleared things up! We're proceeding to testing with creating tickets via the requests endpoint using token auth.
Thanks for your support on this Dwight. Much appreciated.
One additional question in fact, that I couldn't see an answer to in documentation;
What happens when the rate limit is reached?
HeyO Jason,
I believe the rate-limit for authenticated calls to the requests endpoint just pulls from the normal pool of requests as documented here. I did some testing this morning and found this to be the case:
Please feel free to reach out to Support if you're seeing otherwise or have questions specific to your account!
Got it - what I'm seeking to understand is if we breach this limit, what is the expected behaviour? Are we prevented from accessing the API for a time limit - if so, how long? Is this time limit fixed or is it variable?
Ope! Sorry - forgot to address that portion of your earlier post.
The expected behavior is that any other request to the Support API would receive a 429 as you mentioned. That retry_after value should be 60s from whenever the last request was made. This is not to the end of the current minute, but certainly within 2 minutes assuming there isn't a deluge of incoming requests.
Please sign in to leave a comment.