Rate Limit
The Backlog API limits the number of requests per minute that users can send to the API server. This limit applies to the following request types.
Request Types
Read
GET requests, except for Search and Icon
Update
POST, PATCH, and DELETE requests
Search
Icon
Request Rate Limits
The request rate limit varies for the Free and Paid plans, and for each of the above request types.
You can retrieve the latest limits with the Get Rate Limit doc.
We may also apply stricter limits if the Backlog system is under high load and negatively affecting response time.
Response
Status Line
The API servers will return a 429 Too Many Requests response to any requests exceeding the maximum number of requests per minute. For more on the body of 429 responses, please see the Error Response doc.
Response Header
The API servers will add the following HTTP headers into responses so that you know your current rate limit status.
| HTTP Header Name | Description |
|---|---|
| X-RateLimit-Limit | The maximum number of requests you are permitted to make per minute |
| X-RateLimit-Remaining | The number of requests remaining in the current rate limit window |
| X-RateLimit-Reset | The time at which the current rate limit window resets in UTC epoch seconds |
Example of Response Header
In this example, a request was sent to the update API at 0:00:00 on November 16, 2020(UTC), and eight requests had already been executed. The response header shows that there are 142 accesses left and that the number of requests will be reset at 0:01:00 on November 16, 2020(UTC).
- X-RateLimit-Limit: 150
- X-RateLimit-Remaining: 142
- X-RateLimit-Reset: 1605484860
Best practices
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.
Attention
This limit is per user, not per API key. If a user creates API key A and API key B, they will be subject to the same limitation across both.
When using API software provided by Nulab, keep in mind that these requests will also count towards your rate limit. When running software in parallel, the total number of requests cannot exceed the maximum number of requests you are permitted to make per minute.