Account status
The seven account statuses, which ones stop live calls, and what to do about each.
Product page: OnlyFans agency API
Every account has one status in plain words. Read it before a long task, and whenever a call fails with account_unavailable.
The statuses
| Status | Label | Live calls | What it means | What to do |
|---|---|---|---|---|
healthy | Healthy | Work | The session works and the account is syncing, or on Fanvue, Fanvue accepts the access the creator gave. | Nothing. |
syncing | Syncing | Work | Just linked. The first sync is still running. Fanvue accounts never use it. | Read as usual. History fills in over the next minutes, so totals can be low until then. |
needs_relink | Needs relink | Stopped with account_unavailable | The platform signed the session out, a Fansly sign-in failed, or Fanvue stopped accepting the access the creator gave. | Send the creator a new hosted link. The synced history stays in place. |
awaiting_2fa | Awaiting 2FA | Stopped with account_unavailable | The platform asked for a two-factor code. Fanvue accounts never use it. | Send the creator a hosted link so they can enter the code. |
awaiting_selfie | Awaiting selfie | Stopped with account_unavailable | OnlyFans asked for face verification. Fansly and Fanvue accounts never use it. | Send the creator a hosted link so they can finish the selfie check. |
restricted | Restricted | Stopped with account_unavailable | OnlyFans limited the account. Fansly and Fanvue accounts never use it. | The creator has to resolve it with OnlyFans. BetterFans Link cannot lift a restriction. |
disconnected | Disconnected | Stopped with account_unavailable | There is no usable session. | Send the creator a hosted link to connect the account again. |
statusReason holds one plain sentence about a status that is not healthy. Show it to people as it is.
Fansly accounts
A Fansly account uses five of the statuses: healthy, syncing, awaiting_2fa, needs_relink and disconnected. Fansly has no selfie step and no restriction, so a Fansly account is never awaiting_selfie or restricted.
healthywhen the session works. A newly linked account issyncinguntil its first full sync finishes.awaiting_2fawhile the sign-in waits for the code Fansly sent.needs_relinkwhen the sign-in failed, when the session has ended, or when Fansly signed the creator out.disconnectedin every other case.
A sync that stops early, for example during a Fansly outage, does not change the status. The account stays healthy, and lastSyncedAt says how fresh its data is.
Fanvue accounts
A Fanvue account uses three of the statuses: healthy, needs_relink and disconnected. The creator signs in on Fanvue's own page and BetterFans Link keeps no synced copy, so a Fanvue account is never syncing, awaiting_2fa, awaiting_selfie or restricted, and lastSyncedAt is always null.
healthywhile Fanvue accepts the access the creator gave BetterFans Link.needs_relinkwhen Fanvue stops accepting it, for example because the creator removed BetterFans under Connected apps on Fanvue.disconnectedwhen the account is not connected anymore.
Every read of a Fanvue account's data asks Fanvue, so a Fanvue account that is not healthy answers each one with account_unavailable, not only live ones. Get account still answers, without asking Fanvue, with the status and every count at 0.
When live calls stop
Five statuses stop every live call on the account: needs_relink, awaiting_2fa, awaiting_selfie, restricted and disconnected. While the account is in one of them:
- Reads without
fresh=truekeep working and say how old they are inmeta.asOf. - Live reads, such as
fresh=true, Call OnlyFans and Call Fansly, and every read of a Fanvue account but Get account, fail with409account_unavailable. The error'saccountStatusholds the status. - Writes need a working session too. Wait for the account to be
healthybefore you ask for one.
{
"error": {
"type": "account_unavailable",
"code": "account_unavailable",
"message": "The platform is not accepting calls for this account right now.",
"hint": "See error.accountStatus. Reads without fresh=true still work.",
"accountStatus": "needs_relink",
"docsUrl": "https://betterfans.link/docs/errors#account-unavailable"
},
"requestId": "req_7Hq2LmX9pRt4VbN8cKe3WzYa"
}Do not retry account_unavailable in a loop. The status changes only when the creator acts, or when OnlyFans lifts a restriction.
Fixing a status
Most statuses need the creator, so send them a hosted link. In the dashboard, choose Relink on the account, then Send the creator a link to sign in themselves. From code, call Create link. The hosted page walks them through signing in again, entering a 2FA code or taking the selfie. The synced history stays in place, and when they finish the account goes back to healthy.
restricted is different. OnlyFans limited the account, and only the creator can resolve that with OnlyFans. It never happens on Fansly or Fanvue.
Watching for changes
Subscribe to account.status_changed to hear about a change as it happens, with the previous and the new status. List accounts and the MCP tool account_health return the current status at any time.