Rate limits and quotas
Two limits apply to a key: requests a minute, and calls a month. Anonymous callers have a minute limit and a daily limit per IP. Every response tells you where you stand.
Limits by plan
| Plan | Requests a minute | Calls | Tracked companies | Rows per page |
|---|---|---|---|---|
| Anonymous (no key) | 10 | 100 a day per IP | 0 | 10 |
| Free (€0) | 20 | 1,000 a month | 100 | 25 |
| Starter (€49 / month) | 60 | 25,000 a month | 1,000 | 100 |
| Pro (€199 / month) | 300 | 250,000 a month | 10,000 | 100 |
| Business (€499 / month) | 600 | 1,000,000 a month | 50,000 | 100 |
| Scale (€999 / month) | 1200 | 4,000,000 a month | 200,000 | 100 |
| Trial (7 days) | 60 | 5,000 in the trial | 500 | 100 |
At the limit the API stops until the 1st (UTC); there is no overage bill. Upgrade at any time, the same key keeps working. The monthly quota counts calendar months in UTC. Anonymous callers are also limited per network (a shared office or proxy range counts together), and each route has a daily anonymous budget across all callers. A free key moves you out of all of that. Plans and prices: pricing.
Headers on every response
| Header | Meaning |
|---|---|
x-ratelimit-remaining | Requests left in the current window (a minute, or the day for anonymous callers). |
x-ratelimit-reset | When the window resets, as a Unix timestamp in seconds. |
retry-after | On a 429 or 503: seconds to wait before the next try. |
x-quota-limit | Your plan’s calls per month (keyed calls only). |
x-quota-remaining | Calls left this month; 0 on a quota_exceeded answer. |
x-quota-overage | Calls past the quota, when overage is switched on for your plan. |
x-arcadium-anon | true on anonymous answers: a preview with short lists. A free key removes it. |
x-cache | hit when the answer came from the shared cache (free site tools and anonymous lookups). |
Read your own numbers: GET /v1/me shows your plan and usage, and the headers show the rest.
curl -s -D - -o /dev/null "https://api.arcadiumdata.io/v1/me" \
-H "Authorization: Bearer $ARCADIUM_API_KEY" | grep -i "x-ratelimit\|x-quota"From a browser on another site the headers are readable because the API lists them in Access-Control-Expose-Headers for allowed origins (the playground shows them).
When you get a 429
rate_limited: too many requests this minute (or the anonymous daily limit). Wait forRetry-Afterseconds and retry.too_many_in_flight: too many requests running at once. Keep a few in parallel at most.quota_exceeded: the month's calls are used up. Upgrade on /account/ (the same key works at once) or wait for the 1st.
Spread bulk jobs: send requests at a steady pace under your per-minute limit instead of in bursts. Details per code: error codes.
Questions
What counts as one call?
One HTTP request is one call, whatever the page size.
Do I get blocked for hitting the limit?
No. A 429 means wait and retry. Repeated hammering after a 429 only delays your own window; use the Retry-After header.
Why does an anonymous call answer 401 or 503?
Without a key the API serves point lookups of one entity (one company, one pay band) as previews. List and search calls need a free key (401 key_required), and under heavy anonymous load some routes serve recent cached answers only (503 anon_strict). A free key avoids both.