Per-minute rate limit
Each key allows a fixed number of requests per rolling 60-second window — 60 per minute by default, configurable per key. Exceeding it returns:Retry-After header (in seconds) telling you when to try again:
Daily quota
A key can optionally have a daily quota — a cap on resolve calls per UTC day. It is off by default (no cap). When set and reached, requests returnquota_exceeded:
Retry-After.
Both
rate_limited and quota_exceeded use HTTP 429 and send Retry-After.
Branch on the code field to tell them apart: a per-minute limit clears in a minute; a
daily quota only clears at the next UTC midnight.Retry-After
Retry-After is the number of seconds to wait before retrying. It currently defaults to
60 for both 429 codes. Always read it from the response rather than hard-coding a value —
respect whatever the header says.
Backoff guidance
1
Respect Retry-After first
On a
429, wait at least Retry-After seconds before the next attempt. Never retry a
429 immediately.2
Exponential backoff for 5xx
For
provider_down (503) and transient resolve_failed (502), back off exponentially:
e.g. 0.5s, 1s, 2s, 4s, with jitter, capped at a few seconds.3
Cap attempts
Give up after a small number of attempts (3–5) and surface the error rather than looping
forever.
4
Don't retry 4xx
invalid_request, invalid_key, forbidden_scope, not_found, link_removed, and
unsupported_link won’t change on retry. Fix the request instead.Polling and limits
PollingGET /v1/jobs/{id} counts toward your per-minute limit like any request.
When waiting on a queued job:
- Poll on a 1.5–2s interval, not tighter than ~1s.
- For high volume, use webhooks so you don’t poll at all.
- Reduce request count by batching unrelated work rather than spinning many tight polls.
The official SDKs handle this for you: they automatically retry
429 and 5xx responses,
honor Retry-After, and apply exponential backoff with jitter. See
JavaScript and PHP.