January 25, 2021 6:17 pm

[Important Notice] Backlog will start limiting API requests

To keep Backlog running smoothly, we will begin limiting the number of requests that users can send to the API server per minute. Existing Backlog spaces that exceed the new limits will have until July 2021 to comply with the new restrictions. New Backlog spaces created starting today will have the new limits already in place.

Although we only expect these limitations to be an issue for a small number of our current API users, we recommend that all customers who are using the Backlog API adjust their request transmission interval and implement new request resending processing.

Below, we will explain more about what to expect and what you, the customer, may need to do to comply.

Summary

  1. Background
  2. Types of limitations
  3. Schedule
  4. Rate limit specifications
  5. Best-practices for using the Backlog API

1. Background

There have been several instances where overly-frequent requests have resulted in instability in some of Backlog's functionality.

Until now, we have taken measures such as contacting customers directly to adjust their transmission interval or invalidating individual API keys when especially urgent. However, these measures ultimately still affect other customers because it takes time to recover from these failures.

2. Types of limitations

2.1. Minute and user rate limiting

The Backlog API will reject requests from specific customers when they are overly-concentrated in a short period. This limit is on a minute-by-minute and user-by-user basis.

If a specific user exceeds the limit*, a 429 Too Many Requests response will be returned. The number of permitted requests will reset a minute later.

*This will be explained more in section 4.

For example: Say USER A starts sending API requests at 12:34:10 and reaches the limit at 12:34:30. Subsequent API requests will be rejected with a 429 response, but requests will be accepted a minute later at 12:35:10.

Note:: During the period from 12:34:30 to 12:35:10, requests from other users would still be accepted as usual.

The API servers will add the following HTTP headers into responses so that you can know your current rate limit status.

HTTP header name HTTP header content
X-RateLimit-Limit Maximum number of requests that can be accepted per minute
X-RateLimit-Remaining Number of remaining requests that can be accepted by the time of X-RateLimit-Reset
X-RateLimit-Reset Time when the request count is reset (UNIX time)

Note: This limit is per user, not per API key. If a user creates API key 1 and API key 2, they will be subject to the same limitations across both.

2.2. Rate limits by API type

We will enforce strict restrictions on requests with a high load on the system while limiting laxly on requests with a low load.

We have categorized existing APIs into the following four types and will be restricted more strictly in descending order.

Level of restriction

↑Lax

↓Strict

For more information on the rate-limiting specifications, see the "Rate Limit" chapter in the Backlog API documentation.

2.3. Rate limits by plan

To prevent DoS attacks, we will be restricting free plan spaces more strictly than paid plan spaces.

3. Schedule

3.1. Who is affected

All users who use a Backlog API key will be affected, whether creating their own software or using software provided by Nulab, such as the following:

Software from Nulab sends requests as often as they do not violate rate limits. However, if you run your own software and Nulab-provided software at the same time, or if you run multiple Nulab-provided software simultaneously, you may be at risk of violating the new rate limits.

3.2. Existing Backlog spaces

The new rate-limiting restrictions will go into effect for existing Backlog spaces at the end of July 2021. This gives you approximately 6-months to make any necessary adjustments.

We will add headers for rate limiting (i.e., X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) starting today. If you have a request with an X-RateLimit-Remaining value of 0, the request may be rejected after the new rate limits are applied. Until the deadline, we will not reject requests that exceed the new limits.

3.3. New Backlog spaces

The rate limit restrictions will be applied to all new Backlog spaces starting today.

4. Rate limit specifications

4.1. When using your own software with the Backlog API

If the frequency of your API requests exceed the following thresholds, refer to section 5.

Request type Paid Plan Free Plan
Read Within 600 times / minute Within 60 times / minute
Update Within 150 times / minute Within 15 times / minute
Search Within 150 times / minute Within 15 times / minute
Get icon Within 60 times / minute Within 6 times / minute

You can check whether you’re within the rate limits by ensuring the value of X-RateLimit-Remaining is 0.

Note: If Backlog's system is heavily loaded and there are signs of failure or poor service quality, 429 Too Many Requests responses may be returned less frequently than the above thresholds. For business-critical software, we recommend that you implement a process to resend the request one minute later.

4.2. When using two or more software together with the Backlog API

Please review your software usage so that the Backlog API is not used too much at the same time with the same API key.

4.3. When on the free plan

With the introduction of rate-limiting, the following software will no longer be available on the free plan:

To use these software after July 2021, you can upgrade to the paid plan.

5. Best-practices for using the Backlog API

To avoid violating rate limits, we recommend observing the following best-practices:

  • Make requests for a single user serially. Do not make requests for a single user concurrently.
  • If you are making a large number of Update, Search, or Icon requests for a single user, wait at least one second between each request.
  • When you have been limited, retry after one minute. If you have to shorten the wait time, adjust it using the value of the X-RateLimit-Reset header.
  • Reduce the number of requests by using a cache of the past responses.
  • Reduce the number of requests by using a condition like the updatedSince parameter of Get Issue List.

We do not recommend that one software use the API keys of multiple users to send a request. If such a request is found, we may need to apply stricter rate limits or suspend the use of the API keys.

Thank you for your cooperation regarding these limitations

We apologize for any inconvenience incurred by modifying your own software or workflows. We appreciate your understanding and cooperation as we work to create the best experience possible when working with Backlog.

If you have any questions or feedback, please contact us.

Back to list