Using the API
API rate limits
How many requests a Ranqo API key can make each minute on each plan, the headers that report it, and how to handle a rate-limited request.
Each key can make a set number of requests a minute, depending on the account's plan. The limit belongs to the key, not the account, so two tools with their own keys do not use each other's allowance.
Reading the limit from a response
Every response to a request the key's limit admitted, an error included, reports the key's limit and what is left of it, in the IETF RateLimit header fields:
RateLimit-Policy: "minute";q=60;w=60
RateLimit: "minute";r=42;t=17- In
RateLimit-Policy,qis the key's limit andwthe window in seconds. - In
RateLimit,ris the requests left in this window andtthe seconds until it resets.
A refusal that comes before the key's limit is counted carries no RateLimit fields, such as a key or plan refusal (a 401 or 403), api_key_in_url, a 429 for too many failed attempts or a 503. A 429 from the key's own limit carries them.
GET /v1/account returns the same limit as rate_limit.requests_per_minute.
At the limit
A request over the limit is refused with 429 and the code rate_limited. The Retry-After header, and retry_after_seconds in the body, say how many seconds to wait. Wait that long, then retry; retrying sooner is refused again.
If the service that counts requests is briefly unavailable, the API refuses the request with 503 and service_unavailable rather than serve it uncounted. Its Retry-After is 5 seconds.
Using fewer requests
- A brand is tracked every 7 days, so the numbers change at most once a run. Reading the reports once a day is plenty for a dashboard.
- Reports are kept for 10 minutes for the same window and filters, so asking again within that time returns the same figures, unless a run completes in between.
- Read lists with the largest
limityour tool can handle (see Pagination). - Retry a
429or503after theRetry-Afterdelay, and back off further if it repeats.