Know your hourly complexity budget: API key = 3,000,000 points/user, OAuth app = 2,000,000 points/user, unauthenticated = 100,000 points/IP; any single query is capped at 10,000 points.
Read the response headers X-RateLimit-Requests-Limit / -Remaining / -Reset (UTC epoch ms) and X-Complexity, X-RateLimit-Complexity-Limit / -Remaining / -Reset to track consumption proactively rather than waiting for a failure.
Watch endpoint-specific headers too: X-RateLimit-Endpoint-Requests-Limit / -Remaining / -Reset / -Name, since some endpoints have their own sub-limits.
Estimate complexity before firing large queries: properties cost 0.1 points, objects cost 1 point, and connections multiply by the pagination argument (default 50 if unspecified) — round up to the nearest integer.
On a rate-limited response (HTTP 400 with errors[].extensions.code == "RATELIMITED"), back off until the relevant *-Reset timestamp rather than retrying immediately.
Official docs: https://linear.app/developers/rate-limiting
Known gotchas
Rate-limit errors return HTTP 400 (not 429), with the marker in errors[].extensions.code === 'RATELIMITED' — agents that only check status codes for 429 will miss this.
Unspecified pagination arguments default to 50 items per connection for complexity scoring, so an unbounded nested connection query can burn through the 10,000-point single-query cap quickly.
OAuth apps get a lower per-user complexity allowance (2,000,000) than personal API keys (3,000,000) despite a higher request-count allowance — don't assume OAuth is strictly more generous.
Reset timestamps are in UTC epoch milliseconds, not seconds — a naive parse will schedule retries 1000x too late/early.
Give your agent this knowledge — and 15,600+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?