Handle Jira Cloud REST API rate limits correctly: 429 responses, Retry-After, and the points-based quota

Documented steps

1. Treat 429 Too Many Requests as an expected condition, not an exception. Every Jira integration hits it eventually.
2. On a 429, read the Retry-After response header (seconds) and wait at least that long before retrying. Use it as a FLOOR, not an exact value.
3. Read RateLimit-Reason to know WHICH limit you hit: 'jira-quota-global-based' (global pool), 'jira-quota-tenant-based' (per-tenant pool), 'jira-burst-based' (per-second rate), 'jira-per-issue-on-write' (too many writes to one issue).
4. Use the informational headers to stay ahead of limits: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (ISO 8601, returned with 429), and X-RateLimit-NearLimit which becomes true when under 20% capacity remains — throttle proactively when you see it.
5. Implement exponential backoff with jitter on top of Retry-After: delay = max(retryAfter, base * 2^attempt) + random jitter, capped around 30-60 seconds, with a bounded retry count (about 4) before failing the job.
6. Respect the per-issue write ceilings: roughly 20 writes per 2 seconds and 100 writes per 30 seconds against a SINGLE issue. Serialise and space out multi-step updates to one issue.
7. Reduce request volume structurally: batch with POST /rest/api/3/issue/bulkfetch (100 issues) instead of per-issue GETs, request only the fields you need, and use webhooks instead of polling.
8. If you are building a Forge, Connect or OAuth 2.0 app, budget against the points-based hourly quota (global pool default around 65,000 points/hour; per-tenant pools scale with licensed users). Enforcement of the points-based model begins 2026-03-02.
9. Never retry a non-idempotent write blindly after a timeout — verify whether it landed (for example re-read the issue) before re-posting.