BetterFans Link: the OnlyFans APIBetterFans Link

OnlyFans API rate limits

Every request fits under two limits, one for the key and one for the workspace's plan. Read the RateLimit headers, and on 429 wait for Retry-After.

Product page: OnlyFans agency API

Every request has to fit under two limits. Each key has its own short term limit, so one busy key never slows down another. The workspace also has a rate a minute, set by its plan and shared by all of its keys. Your code only has to read one set of headers and handle one error to stay under both.

Per key

KeyRequests per secondBurst
bfl_live_ and bfl_test_ keys2060
MCP clients connected with OAuth1030

The limit works like a bucket that holds up to the burst and refills at the steady rate. A key that has been idle can send the whole burst at once, then settles to the per second rate.

Who am I returns the key's limit in rateLimit, so your code can read it instead of hard coding it.

Per workspace

The plan sets how many requests the workspace can send in a minute, across all of its keys and MCP clients, in live and test mode.

PlanRequests a minute
Free60
Starter300
Growth1,200
Scale3,000
Enterprise10,000

The minute rolls rather than starting on the clock, so a request stops counting about a minute after it was sent. The Billing page in the dashboard shows your plan's rate and how many requests were rate limited this period. To raise the rate, change plan.

Headers

Every response carries the budget of whichever limit is closer to running out, so the headers always describe the one that will refuse you first.

HeaderMeaning
RateLimit-LimitThe size of that limit: the key's burst, or the plan's requests a minute.
RateLimit-RemainingRequests left right now.
RateLimit-ResetSeconds until the budget is full again.

Slow down when RateLimit-Remaining gets low instead of waiting for a 429.

When you hit a limit

Over either limit, the request fails with 429 rate_limited and a Retry-After header in seconds. Wait that long, then retry. Nothing ran, so retrying is safe for every route.

When the plan's rate refused the request, the error also carries error.limit, so you can tell the two apart. Its name is requestsPerMinute, allowed is the plan's rate and resetsAt is when the next request will fit.

{
  "error": {
    "type": "rate_limited",
    "code": "rate_limited",
    "message": "Too many requests.",
    "hint": "Wait for Retry-After seconds.",
    "limit": { "name": "requestsPerMinute", "allowed": 300, "used": 300, "resetsAt": "2026-11-02T15:04:12Z" },
    "docsUrl": "https://betterfans.link/docs/errors#rate-limited"
  },
  "requestId": "req_7Kq2mX9pLr4tVw8YbN3cHd"
}

The same retry handles both:

async function call(url: string, init: RequestInit = {}, tries = 3): Promise<Response> {
  const res = await fetch(url, init);
  if (res.status === 429 && tries > 1) {
    const wait = Number(res.headers.get("Retry-After") ?? "1");
    await new Promise((r) => setTimeout(r, wait * 1000));
    return call(url, init, tries - 1);
  }
  return res;
}

The request log lists every 429 with the key and route that sent it. Filter by status to find them.

Staying under it

  • Page with limit=100 instead of many small pages.
  • Cache what does not change often, such as the account list and fan lists.
  • Prefer webhooks to polling. message.received and transaction.created tell you when there is something new.
  • Use fresh=true only when you need a live answer. Live reads are slower, so a loop of them holds your budget longer.
  • Run large jobs with a small, fixed number of requests in flight instead of firing them all at once.
  • Spread scheduled jobs across the minute instead of starting them all at the top of it. Every key in the workspace shares the plan's rate.

On this page