Rate limits & tiers

DoesItARM follows free data, paid capability: the single-title lookup and search are free; you pay for capability the free read can’t give you. Limits exist to keep the free tier sustainable, not to meter the lookup itself.

The budget

Tier	Reads	Paid capabilities
Anonymous (no key)	Lowest per-IP bucket	—
Free key (`dia_free_`)	Higher per-key bucket	—
Paid (`dia_live_`)	Highest bucket	Change feed, bulk/export, SLA, license, enterprise reports

The exact numbers ship with the live API; treat the tiers, not the integers, as the contract. See Pricing for plans and the machine-readable block.

Headers on every response

Every response — not just a 429 — carries your remaining budget, so you never have to guess:

Header	Meaning
`RateLimit-Limit`	Requests allowed in the current window
`RateLimit-Remaining`	Requests left in the window
`RateLimit-Reset`	Seconds until the window resets

These follow the IETF ratelimit-headers draft (the pre-08 three-header form, the widest-supported variant). A 429 adds Retry-After (seconds).

When you hit the limit

A 429 returns the standard error envelope with both a Retry-After header and an upgradeUrl in the body:

HTTP/1.1 429 Too Many Requests
Retry-After: 30
RateLimit-Limit: 60
RateLimit-Remaining: 0
RateLimit-Reset: 30
Content-Type: application/json

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limited",
    "message": "Free tier allows 60 requests/min. Retry in 30s or upgrade.",
    "docsUrl": "https://docs.doesitarm.com/api/rate-limits/",
    "upgradeUrl": "https://doesitarm.com/early-access",
    "requestId": "req_01J5K6Q8ZD"
  }
}

Handle it in two steps: wait Retry-After seconds and retry, or — if you’re hitting the ceiling routinely — follow upgradeUrl to Early Access. You can trip this deterministically in testing with the 429-demo identifier from the Quickstart.