Rate limiting guide for Jira and Confluence

#1

Recently we added a guide explaining how rate limiting works in Jira and Confluence. The same guide applies to both Jira and Confluence, but is available in both documentation sets:

We realise the current rate limiting solution has pitfalls. There is a section at the end of the guide identifying the major known deficiencies.

5 Likes
Jira Core - 429 API Limit Request
#2

Hi @dmorrow,

thanks for sharing this documentation, which is very useful.

I have a question on the Rate Limiting documentation for Jira.

The documentation states the following:

You can retry a failed request if:

  • It is safe to do so from the perspective of the API (e.g. the API being called is idempotent).
  • A small retry threshold has not been reached.
  • The response indicates a retry is appropriate ( Retry-After header and/or 429 status).

I assume that means if all conditions are met.

Does it mean that an app should retry any REST call if and only if it receives either a 429 error or a Retry-After header? And thus that any other error (403, 500, 503, 509, which are also returned by certain REST endpoints in overloading situations) should not be retried unless they are accompanied by a Retry-After header? A common error code when Jira is overloaded is a 403 error with no error message in the body (in fact, an HTML response body instead of a JSON response body), usually indicating a DB connection pool error. Are these errors marked with a Retry-After header?

In general, it would be nice to include in the documentation a full, validated pseudo-code algorithm showing how exactly apps should handle errors related to rate limits, including how to identify them (which is not shown in the current algorithm). For that, you’d need to test all REST endpoints one by one by throwing a million requests at them until they fail, and check the error code they return then and add that case to the algorithm.

Thanks,
David

1 Like
#3

Hi @david2,

Thanks for your comments and keeping me on my toes.

Firstly, I should make it clear that the guide provides recommendations rather than rules. I wrote the guide from a somewhat theoretical standpoint because I don’t have a real world app stressing APIs and consequently don’t have first hand experience in dealing with rate limit responses from these APIs. If the guide doesn’t cater to specific use cases, then I’m happy to factor in improvements.

I intended an AND relationship between the bullet list items. I’ll fix the guide to make this clear.

With regard to the various error responses you referred to (403, 500, etc), there may be circumstances where a retry makes sense, but it’s somewhat out of scope of the rate limiting guide. If there are specific use cases and error responses that should be added to the guide, then maybe we can discuss them in more detail. For instance, I wasn’t aware of the 509 error code.

Regards,
Dugald

1 Like
#4

Hi @dmorrow,
I didn’t realize you were the author of that documentation. I thought it came directly from the Jira dev team. My comments must have felt personal and I apologize for that.

And that indeed explains why you can be neither prescriptive nor exhaustive. It would require an in-depth knowledge of how exactly each REST API endpoint is coded and implements rate-limiting (or fails to do so and thus reacts to errors when overloaded).

And of course that’s probably the root of the problem - the various ticket on EAN about implementing a real rate-limiting solution are still pending.

Anyway, based on your knowledge of the API, would you recommend trusting only the 429 error code and the Retry-After header, and treat all other errors as permanent failures?

Also, is there any way to know which REST endpoints can return a 429 error or a Retry-After header? Is this something that could be added to the official REST API documentation, alongside the other errors that are already documented?

Thanks again,
David

1 Like
#5

Hi @david2,

No problems, I didn’t take offence. I think there are responses other than 429 which may be transient, but there may not be a means of determining if or when a re-try may be successful. I can how this leads to your suggestion of treating them as a permanent error, at least as far as retries are concerned. Having said that, I can imagine some use cases where we might be able to provide more specific guidance regarding retries.

In terms of documenting which APIs can return 429 errors, my understanding of the implementation is that any API can return a rate limit response, however, some may be more likely than others since it depends on the resources consumed by their implementation.

Regards,
Dugald

1 Like