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.

LoopHaven 0.2.0 · defaults verified on 16 November 2026

Telling them apart

Local budgetLooperman quota
Who sets itthis processLooperman
Default30 page reads / 60 sper item, per day
Applies topage fetches (search, detail)downloads (/getfiles/)
detail begins withlocal rate limit reachedthe upstream refusal
What clears itwaiting out the window; cached reads are freewaiting until tomorrow — nothing else
Can you raise ityes, LOOPHAVEN_RATE_LIMITno

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:

ResponseMeaningWhat LoopHaven does
audio/wav, audio/mpegthe filestreams it, keeps the real filename
text/htmla quota page or a login page502; writes nothing
429daily limit reached429, passed through
401no session open401, 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:

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.