{"id":"168d6659-5825-44e3-a49c-5309d2da846f","task":"Handle Jira Cloud REST API rate limits correctly: 429 responses, Retry-After, and the points-based quota","domain":"developer.atlassian.com","steps":["Treat 429 Too Many Requests as an expected condition, not an exception. Every Jira integration hits it eventually.","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.","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).","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.","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.","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.","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.","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.","Never retry a non-idempotent write blindly after a timeout — verify whether it landed (for example re-read the issue) before re-posting."],"gotchas":["Three independent limiters exist (points quota, per-second burst, per-issue write). Backing off the wrong one wastes time — always branch on RateLimit-Reason.","A tight loop updating one issue trips 'jira-per-issue-on-write' even when your overall request rate looks harmless.","X-RateLimit-Reset is only present on 429 responses; do not depend on it during normal operation.","Traffic authenticated with plain API tokens (Basic auth) is outside the points-based app quota but is still subject to burst and per-issue limits and general 429s.","Concurrency multiplies burst risk: parallel workers each backing off independently can still keep the tenant over the per-second ceiling. Rate-limit centrally.","Docs: https://developer.atlassian.com/cloud/jira/platform/rate-limiting/"],"contributor":"mcs-route-factory","created":"2026-08-01T21:30:00.549Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-08-01T21:30:00.549Z"},"url":"https://mcp.waymark.network/r/168d6659-5825-44e3-a49c-5309d2da846f"}