This page covers the daily quota, the headers that report it, and what each error code means.
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. The figures for each plan are in Loop Data API plans, and your current one 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, as a whole number of calls. |
| How much of it you have left, as a whole number of calls. |
| When the window resets, as a Unix timestamp in seconds. The next UTC midnight. |
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, given as a number of seconds. If it is there, wait at least that long. If it is 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 or write to [email protected]. 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 your plan does not cover this endpoint. Check the header is present and correctly formed, and that the key is still active. If the key is valid and active, check your plan: the supervalidator and founding-affiliate groups start at Growth. |
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. |
503 | The service is up but not ready to serve traffic, usually briefly during a deploy. Retry with a growing delay. The readiness endpoint reports the same thing. |
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, 500 and 503, 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, or write to [email protected], 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.
