Best practices for avoiding rate limiting

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

The rate limits for the Zendesk APIs are outlined in Rate limits in the API reference. 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

You can use the API dashboard in Admin Center to monitor your API activity against your rate limit in the last 24 hours. See Tracking API activity against your rate limit in Zendesk help.

The following response headers contain the account's rate limit and the number of requests remaining for the current minute:

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

Handling errors caused by rate limiting

If the rate limit is exceeded, the API responds with a 429 Too Many Requests status code.

It's best practice to include error handling for 429 responses in your code. If your code ignores 429 errors 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 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 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 handle rate-limit errors:

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

Node.js

The following snippet shows how you can handle rate-limit errors in JavaScript for Node.js.

const axios = require("axios")

async function requestWithRateLimit(url, username, password) {
  const response = await axios.get(url, {
    auth: {
      username,
      password
    }
  })
  if (response.status === 429) {
    const secondsToWait = Number(response.headers["retry-after"])
    await new Promise(resolve => setTimeout(resolve, secondsToWait * 1000))
    return requestWithRateLimit(url, username, password)
  }
  return response
}

Browser JavaScript

The following snippet shows how you can handle rate-limit errors in client-side JavaScript for the browser.

async function requestWithRateLimit(url, accessToken) {
  const options = {
    method: "GET",
    headers: {
      Authorization: `Bearer ${accessToken}`
    }
  }
  const response = await fetch(url, options)
  if (response.status === 429) {
    const secondsToWait = Number(response.headers.get("retry-after"))
    await new Promise(resolve => setTimeout(resolve, secondsToWait * 1000))
    return requestWithRateLimit(url, accessToken)
  }
  return response
}

Note: To make an authenticated request from the browser to a Zendesk API, you must authenticate the request using an OAuth access token. For more information, see Making client-side CORS requests to the Ticketing API.

Python

The following snippet shows how you can handle rate-limit errors in Python.

import requests
import time


def request_with_rate_limit(url, username, password):
    auth = (username, password)
    response = requests.get(url, auth=auth)
    if response.status_code == 429:
        seconds_to_wait = int(response.headers["Retry-After"])
        time.sleep(seconds_to_wait)
        return request_with_rate_limit(url, username, password)
    return response

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 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.

4. Use bulk and batch endpoints, such as Update Many Tickets, that let you update up to 100 tickets with a single API request.

Regulating the request rate

If you regularly exceed the rate limit, update your code to distribute requests more evenly over a period of 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, you can use the following response headers to monitor your account's rate limit and the number of requests remaining for 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, such as Update Many Tickets or Ticket Bulk Import, will reduce calls.