Looperman download limits and 429s
Two different limits return the same 429, and they
are not interchangeable. One is a local budget — 30 page reads per
60 seconds by default, set by LOOPHAVEN_RATE_LIMIT — that exists
to stop your own retry loop from getting your account throttled. The other is
Looperman's own download quota, which is per item and per day and cannot be
raised, shared or routed around. The detail field says which one
you hit.
Telling them apart
| Local budget | Looperman quota | |
|---|---|---|
| Who sets it | this process | Looperman |
| Default | 30 page reads / 60 s | per item, per day |
| Applies to | page fetches (search, detail) | downloads (/getfiles/) |
detail begins with | local rate limit reached | the upstream refusal |
| What clears it | waiting out the window; cached reads are free | waiting until tomorrow — nothing else |
| Can you raise it | yes, LOOPHAVEN_RATE_LIMIT | no |
The local counter is visible before you hit it, on the health route:
curl "http://127.0.0.1:8000/api/health"
{
"status": "ok",
"auth": { "logged_in": true, "username": "Benmallessa" },
"rate_limit": {
"max_requests": 30, "window_seconds": 60,
"recent_requests": 3, "remaining": 27
}
}
Why a local limiter at all
Because the natural way to write a scraper is a loop, and the natural failure of a loop is that it stops looking like a person. Thirty page reads a minute is well above browsing speed and well below anything that looks like harvesting. Cached reads do not count, so paging back through results you already fetched costs nothing.
# slower, for a shared connection or a large batch
LOOPHAVEN_RATE_LIMIT=10
A malformed value does not crash the process: it falls back to 30. That is deliberate — an environment variable should not be able to prevent the module from importing.
What a quota refusal actually looks like
Looperman does not always answer a spent quota with a status code. Often it
answers 200 with an HTML page, which is the reason a download
route validates what came back before writing anything:
| Response | Meaning | What LoopHaven does |
|---|---|---|
audio/wav, audio/mpeg | the file | streams it, keeps the real filename |
text/html | a quota page or a login page | 502; writes nothing |
429 | daily limit reached | 429, passed through |
401 | no session open | 401, before touching the site |
For loops the check goes further: the payload has to start with
RIFF…WAVE before it is called a WAV. That looks paranoid until you
have saved a quota page as a five-second .wav and only noticed
inside a DAW, days later, with no record of which fetch produced it.
Nothing is retried automatically
This is the deliberate part. A retry on 429 is
indistinguishable from insisting, and the thing being protected is not the
software's uptime — it is your account. So:
- No backoff-and-retry loop. A
429stops and reports. Waiting is a decision made by whoever is running the thing. - No proxy rotation, no second account. One person, one account, one quota.
- No silent format substitution. An acapella is an MP3
whatever you ask for; a failed file inside a ZIP becomes
ERROR_<id>.txtwith the reason, not a renamed neighbour.
If you need more than the quota allows, the answer is a different source — a paid sample library, a Creative Commons collection, your own recordings. A tool that works around the limit is a tool that gets the limit tightened for everyone, including you.
A session that lies is worse than no session
Most “download broken” reports are a stale cookie. Cached state
would say logged_in: true forever, so the check is re-verified
against /account/ on every status call:
curl "http://127.0.0.1:8000/api/auth/status"
{ "logged_in": false, "username": null, "user_id": null }
The same fact shows up on a detail page as
"download_link_present": false — the page has no
/getfiles link for that item. Sixteen links appear when you are
logged in; zero when you are not. That difference, not a parse error, is what
to check first.
Next: the download flow in Python, or narrow the search so you spend less quota finding the right file.