How the quota works
Your allowance is counted per API key, over a UTC day. It resets at the start of the next UTC day, not twenty four hours after your first call, so the reset moment is the same for everyone regardless of where you are.
Every request counts, whether it returns one record or a hundred. That is why asking for larger pages is cheaper than asking for many small ones.
The size of your allowance depends on your plan. Your current one is on your plan page, and it is also reported back to you on every response, which is the more reliable place to read it from.
The headers that tell you where you stand
Header | What it tells you |
| Your ceiling for the current UTC day |
| How much of it you have left |
| When the window resets |
Read these rather than counting calls in your own code. Your counter and ours will drift apart the moment a retry, a failed deploy or a second instance enters the picture.
When you hit the limit
You get a 429. Nothing is broken and nothing is blocked permanently. It means you have used the allowance for this UTC day.
A 429 may carry a Retry-After header. If it does, wait at least that long. If it does not, back off and widen the gap between attempts instead of retrying in a tight loop, which only burns the next window as well.
Requests made without a key are throttled separately and more tightly, so if you are seeing 429 on unauthenticated calls, the fix is usually to send the key rather than to slow down.
If you keep running out and the next plan up is not the right shape for what you are doing, message us from this page. There are arrangements beyond the listed plans.
What the other codes mean
Code | Usual cause, and what to do |
400 | The request itself is wrong: a missing parameter, a malformed identifier, a limit above the maximum, a badly formed date. Fix the request. Retrying it unchanged will fail again. |
401 | The key was missing, malformed, revoked, or does not cover this endpoint. Check the header is present and correctly formed, and that the key is still active on your account. |
404 | The path is wrong, or the record genuinely does not exist. Check the address and the identifier before assuming data is missing. |
429 | Quota used for this UTC day. See above. |
500 | Something failed on our side. Retry with a growing delay. If it persists, tell us, because that one is ours to fix. |
A useful rule: 4xx means change something before you try again, 5xx means try again later, and 429 means wait for the window.
Building something that stays inside the limits
Read the remaining count from the response headers and slow yourself down before you hit zero rather than after.
Back off progressively on 429 and 500, and add a little randomness to the delay so that several of your own instances do not retry in step with each other.
Cache what does not change. Historical rounds and settled records are not going to look different an hour from now.
Ask for the largest page you can rather than walking the same data in small steps, and request only the range you actually need.
If something does not add up
Message us from this page with the endpoint, the status code, the rate limit headers you received, roughly when it happened and what you expected instead. Please do not send us your key.