Account status
The seven account statuses, which ones stop live calls, and what to do about each.
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. | Nothing. |
syncing | Syncing | Work | Linked in the last 30 minutes. The first sync is still running. | 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 | OnlyFans signed the session out. | Send the creator a new hosted link. The synced history stays in place. |
awaiting_2fa | Awaiting 2FA | Stopped with account_unavailable | OnlyFans asked for a two-factor code. | 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. | Send the creator a hosted link so they can finish the selfie check. |
restricted | Restricted by OnlyFans | Stopped with account_unavailable | OnlyFans limited the account. | 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.
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=trueand Call OnlyFans, 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": "OnlyFans is not accepting calls for this account right now.",
"hint": "See error.accountStatus. Reads without fresh=true still work.",
"accountStatus": "needs_relink",
"docsUrl": "https://app.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. Create a hosted link from the Linking page or with Create link and send it to them. 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.
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.