Core concepts .md

Rate limits & fair use

FlickList caps how many requests a single credential can make per hour, so build your client to stay under it instead of discovering the ceiling in production.

{
  "error": "rate_limited"
}

Retry-After: 60

The published limit is 1,000 requests per hour per credential (a session token or an API key). This is a fair-use ceiling. When you exceed it, the response is 429 with a Retry-After header telling you how many seconds to wait. Honor that value before your next request instead of retrying immediately or backing off on a schedule of your own:

retry_after=$(curl -sD - -o /dev/null "$URL" | grep -i '^retry-after:' | tr -dc '0-9')
sleep "$retry_after"

const res = await fetch(url, { headers });
if (res.status === 429) {
  const retryAfter = Number(res.headers.get('retry-after'));
  await new Promise((r) => setTimeout(r, retryAfter * 1000));
}

import time
if r.status_code == 429:
    time.sleep(int(r.headers["Retry-After"]))

Check before you fetch#

The most common way to reach the ceiling is polling large collections on a timer whether or not anything changed. Before re-fetching any collection wholesale, check GET /v3/sync/last_activities. It returns a timestamp per data domain (watchlist, ratings, history, and so on) for a fraction of the cost of a full fetch. Compare those timestamps to what you last stored and only pull the collections that actually moved. That's the intended pattern for keeping a client in sync without walking every page of every collection on every poll.

Scrobble heartbeats fit comfortably#

If you're building a player integration, re-posting start every 30 to 60 seconds while something plays is expected behavior, not something to budget carefully around. That cadence works out to roughly 60 to 120 requests per hour for a single active playback session, well under the 1,000/hour limit even alongside other traffic your client sends.