Fanvue API Documentation

The API allows 200 requests per minute for each user your app acts for, counted per OAuth client, and returns 429 with a Retry-After header when the budget is spent. Plan against it before you launch, and check the rules below when you start seeing 429 responses.

Don’t poll chat endpoints for new messages. Polling is the main cause of 429 responses. Subscribe to webhooks for new events and pull deltas in bulk with Efficient chat sync.

How the budget works

The default limit is a budget of 200 points per 60 seconds. Each request spends one point, and the budget refills to full at the end of the window. It’s counted per OAuth client per user, so each user who authorises your app has their own budget and one user’s traffic never affects another’s. Agencies can be granted higher limits on request. A higher limit is shared by the whole agency team as one budget per OAuth client, rather than one per team member. Read X-RateLimit-Limit on the response rather than assuming 200. The count is global per identity. Spreading traffic across servers, processes or IP addresses does not multiply the budget, because every request decrements the same counter.

How the bucket is keyed

Routes under /creators/{creatorUserUuid}/... key the budget on the creator as well, so each creator you act for has a separate 200-point budget. Every other route, including the aggregate /agencies/* endpoints, draws from the single budget of the calling user. Use the creator-scoped routes for high-volume per-creator work and keep the shared budget for cross-creator queries.

Capacity planning

Re-polling chats for new messages is the most common cause of throttling. Polling every chat on a fixed interval scales with creators × chats × poll frequency, and most of those requests return nothing new. Two paths cost less:

Use webhooks instead of polling. Subscribe to creator.message.received and creator.message.read and let Fanvue push events to you. Steady-state request cost is zero.
When you must pull, pull deltas. Call POST /chats/messages/batch with a sinceMessageUuid cursor to fetch only what changed across up to 50 chats in one request.

Efficient chat sync covers both with a worked request budget. When you estimate headroom for a growing creator count, remember how the bucket is keyed. Creator-scoped routes each have their own 200-point budget, so per-creator work scales with the number of creators. Aggregate /agencies/* calls share one budget, so reserve it for cross-creator queries.

Headers

Every rate-limited response carries the limit headers, not only a 429, so you can slow down before you hit zero. API conventions lists them alongside the other headers every endpoint shares.

Header	Meaning
`X-RateLimit-Limit`	Points allowed in the current window for the limit that applied to this request.
`X-RateLimit-Remaining`	Points left in the current window.
`X-RateLimit-Reset`	Unix timestamp in seconds when the window resets.
`Retry-After`	On a `429`, and on the database-timeout `503`: seconds to wait before retrying.

A request over the budget returns:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1672531200
Retry-After: 45

{ "error": "Too many requests" }

Per-endpoint limits

A few endpoints carry their own limit, with its own counter, fixed regardless of agency limits. The /v1/chats/lists/dynamic/* routes and POST /v1/webhooks/test spend a point on both their own counter and the 200-point budget. The other routes in the table carry only their explicit limit.

Method and path	Limit	Keyed by
`POST /onboarding/creators`	10 per 60 s and 25 per day	OAuth client and user
`POST /chats/statuses`	80 per 60 s	OAuth client and user
`POST /creators/{creatorUserUuid}/chats/statuses`	80 per 60 s	OAuth client, user and creator
`GET /creators/{creatorUserUuid}/subscribers/online`	80 per 60 s	OAuth client, user and creator
`GET /creators/{creatorUserUuid}/media/uploads/{uploadId}/parts/{partNumber}/url`	1000 per 60 s	OAuth client, user and creator
`POST /v1/webhooks/test`	30 per 60 s	User
`GET /v1/chats/lists/dynamic/dimensions`	30 per 60 s	User, shared with the creator-scoped twin
`GET /v1/chats/lists/dynamic/memory-topics`	30 per 60 s	User, shared with the creator-scoped twin
`POST /v1/chats/lists/dynamic/preview/count`	60 per 60 s	User, shared with the creator-scoped twin
`POST /v1/chats/lists/dynamic/preview/members`	60 per 60 s	User, shared with the creator-scoped twin
`POST /v1/chats/lists/dynamic/translate`	10 per 60 s, and 100 per day per creator	User for the minute cap, OAuth client and creator for the daily cap
`POST /v1/chats/lists/dynamic`	20 per 60 s	User, shared with the creator-scoped twin
`GET /v1/chats/lists/dynamic`	30 per 60 s	User, shared with the creator-scoped twin
`GET /v1/chats/lists/dynamic/{uuid}`	30 per 60 s	User, shared with the creator-scoped twin
`PATCH /v1/chats/lists/dynamic/{uuid}`	20 per 60 s	User, shared with the creator-scoped twin
`DELETE /v1/chats/lists/dynamic/{uuid}`	20 per 60 s	User, shared with the creator-scoped twin
`GET /v1/chats/lists/dynamic/{uuid}/members`	60 per 60 s	User, shared with the creator-scoped twin

Dynamic list limits are keyed on the user alone, so one person calling through several apps draws on one counter. Each dynamic list route and its /v1/creators/{creatorUserUuid}/chats/lists/dynamic/... twin share a counter. X-RateLimit-Limit reports the limit that fired, so a 429 from a dynamic list route shows the route’s own cap rather than 200.

Concurrency and deep pages

At most 6 requests per caller may be in flight at once, where a caller is one OAuth client acting for one user. A seventh request is rejected straight away with 429, Retry-After: 1 and the body { "error": "Too many concurrent requests" }. A slot frees as soon as an in-flight request settles, so a client that retries after 1 second proceeds. This response carries no X-RateLimit-* headers, so branch on the error string to tell it from a spent budget; Error responses shows both 429 bodies. On previous-version list endpoints that page with page and size, a deep page costs more than one point. Pages 1 to 25 cost 1 point. Beyond that, a request costs ceil(page / 25) points, capped at 20, so page 150 costs 6 points. A request that carries the route’s cursor parameter, such as beforeMessageUuid on chat messages, costs 1 point whatever page says. Cursor pagination on /v1 always costs 1 point per request. See Moving to v1.

Handle 429 in code

Wait the number of seconds in Retry-After, then retry. A minimal retry wrapper:

import time, requests

def call(url, token):
    while True:
        r = requests.get(url, headers={
            "Authorization": f"Bearer {token}",
            "X-Fanvue-API-Version": "2025-06-26",
        })
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", 1)))

async function call(url, token) {
  while (true) {
    const r = await fetch(url, {
      headers: {
        Authorization: `Bearer ${token}`,
        "X-Fanvue-API-Version": "2025-06-26",
      },
    });
    if (r.status !== 429) return r;
    const wait = Number(r.headers.get("Retry-After") ?? 1);
    await new Promise((res) => setTimeout(res, wait * 1000));
  }
}

Read X-RateLimit-Remaining on every response and slow down before it reaches zero, rather than waiting for a 429.

Start here

Authentication

API concepts

Guides

Rate limits

How the budget works

How the bucket is keyed

Capacity planning

Headers

Per-endpoint limits

Concurrency and deep pages

Handle 429 in code

​How the budget works

​How the bucket is keyed

​Capacity planning

​Headers

​Per-endpoint limits

​Concurrency and deep pages

​Handle 429 in code

How the budget works

How the bucket is keyed

Capacity planning

Headers

Per-endpoint limits

Concurrency and deep pages

Handle 429 in code