Rate Limits

Limits

To help prevent strain on Trello’s servers, our API imposes rate limits per API key for all issued tokens. There is a limit of 300 requests per 10 seconds for each API key and 100 requests per 10 second interval for each token. Additionally, there is a limit on requests to /1/members/ of 100 requests per 900 seconds. If a request exceeds the limit, Trello will return a 429 error along with a message corresponding to which limit was exceeded. If the amount of 429 errors per API key exceeds 200, Trello will return 429 for the remainder of the API key requests for the remainder of the 10s window.

Rate Limit Errors

When a rate limit has been exceeded, Trello will return a response with a status code of 429 and an error message. The error message should be used to determine whether the key or token limit was exceeded.

For instance, the API token rate limit will return the following JSON response:

1
2
{
  "error": "API_TOKEN_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded"
}

And the API key rate limit will return the following JSON response:

1
2
{
  "error": "API_KEY_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded"
}

Database Time Limits

There may be limits enabled to ensure that expensive API requests are kept under control.

These limits are not common and do not have a clear solution for staying within the limit. If you are to see one of these limits, we recommend that you review your request response sizes and try to break any requests with a large response into smaller individual requests.

API_TOKEN_DB_LIMIT_EXCEEDED: Each token is allotted a specific amount of database query response time. This error indicates that this token is making too many database-expensive calls. Back off of large, expensive calls with this token to avoid hitting the limit again.

Response Size Limits

There may be limits enabled to ensure that too many Trello objects are not returned in a single, large request.

For instance, there is a limit in place to restrict the number of cards that can be returned with their actions in a single call. This error is often hit when making a request for all of a board's cards and their actions. For example:

1
2

curl https://api.trello.com/1/boards/{boardId}/cards?actions=all&filter=all

If this call is not limited on a large board, you may hit the following error:

1
2
{
  "message": "Requested too many cards with action loads, please limit",
  "error": "API_TOO_MANY_CARDS_REQUESTED"
}

Instead, we recommend making additional requests for card’s actions after you’ve received all of the cards from your initial request.

Special Route Limits

We have special limits around endpoints that include user account information. This allows us to make sure that consumers are using these resources responsibly. The three routes with special limits are: /1/members, /1/membersSearch, and /1/search. The much stricter limits on these routes mean that third-party developers should use these resources sparingly.

A single request to /1/members will count against the members limit, the key limit, and the token limit. However, requests to nested resources under the endpoint will not count against the route-specific limit. For instance, a request to /1/members/me/boards/ will not count as a request against the limit for /1/members/.

If you are trying to load a lot of members, the best way to get the information you need is to use the nested resource route for the object the members belong to. For instance, if you want all members on a board? Use /1/boards/:id/members. If you want all members on a Workspace? Use /1/organizations/:id/members.

Working With Rate Limits

Trello's platform includes webhooks as an alternative to regularly polling Trello. By registering a webhook on a Trello object, Trello will reach out to you to notify you of events as they happen.

Additionally, Trello's API includes robust nested resources. For instance, if you want to get all of the data about cards on a board, instead of iterating through all of the card IDs and making individual GET requests to 1/cards/{cardId}, you can get all of the same information from the cards nested resource within the board (1/boards/{boardId}/cards?filter=visible). You can read more about nested resources here.

Rate Limits In Headers

Rate limit information is also returned in headers of the response from Trello. The headers include the following information for both token and key rate limits: the time interval of the limit (in milliseconds), the limit's max, and the remaining request count for the given interval.

Your application should use the information contained in these headers to stay within the rate limit.

For example, a single request within an interval:

1
2
curl -I 'https://api.trello.com/1/members/me?key={yourKey}&token={yourToken}'

Returns the following headers:

1
2
HTTP/2 200
[...]
x-rate-limit-api-token-interval-ms: 10000
x-rate-limit-api-token-max: 100
x-rate-limit-api-token-remaining: 99
x-rate-limit-api-key-interval-ms: 10000
x-rate-limit-api-key-max: 300
x-rate-limit-api-key-remaining: 299
[...]
date: Wed, 17 Jan 2018 20:59:00 GMT