OnlyFans API error codes

Errors come back with an HTTP status and a JSON body. Branch on error.code: it is stable. error.message is for people and can be more specific than the default shown here, so never match on it.

The error body

{
  "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"
}

Retrying

All codes

Codes marked dashboard come from the dashboard and the hosted link page, never from the REST API or MCP.

Invalid request

invalid_parameter

A query parameter has a value the route does not accept, a required one is missing, or the body does not match. error.param names the parameter. Fix the value and send the request again. Unknown query parameters are ignored, so a misspelled name has no effect instead of failing.

invalid_cursor

A cursor belongs to one list with one set of filters. Pass nextCursor back unchanged with the same parameters, or leave cursor out to start again from the first page.

idempotency_key_required

Every POST /v1/accounts/{accountId}/actions needs an Idempotency-Key header. Generate a UUID for each action you intend and send the same value when you retry that action.

method_not_allowed

Call OnlyFans and Call Fansly only read. To send, take back or change anything, create an action instead. It waits for a person to approve it, unless the key has auto-approve on.

not_supported_on_platform

The account's platform does not support this route, action type or tool. Each route in the API reference lists its platforms, and GET /v1/accounts shows each account's platform. For an action, error.param is type. Sending the same request again fails the same way.

Authentication

missing_api_key

Send the key as Authorization: Bearer <key> or in the x-api-key header.

invalid_api_key

No key matches. Check that the whole key was copied and that nothing was added around it. Keys are shown once, so a lost key has to be replaced with a new one.

revoked_api_key

Someone revoked this key in the dashboard, or it was rolled and the old key stopped working. Create a new key.

expired_api_key

The key passed the expiry date set when it was created. Create a new key.

not_signed_in

Dashboard only. The dashboard session ended. Sign in again.

invalid_access_token

Dashboard only. The account access token or OAuth token is not one we issued, someone revoked it, it passed its expiry date, or the person it belongs to is banned. Create a new token on the Account page and replace the old one wherever it is stored. A banned person gets this answer until the ban is lifted. API keys work on /v1, not on the dashboard procedures.

Billing

quota_exceeded

The workspace used every live call its plan includes for this period. error.limit says how many were allowed, how many were used and when the period resets in resetsAt. Synced reads and test mode keep working. Live calls resume at the reset, or at once when an owner upgrades the plan or allows overage on the Billing page. See plans and limits.

plan_limit_reached

The plan does not allow one more of something: an account, a teammate or a webhook endpoint. error.limit.name names the limit, with allowed and used. Nothing you already have is removed. Remove one first, or ask an owner to choose a larger plan on the Billing page. See plans and limits.

Permission

missing_scope

The key has only the read scope and the call needs write. Create a key with the write scope for code that asks for writes.

writes_disabled

Writes are switched off for this account. An owner or admin can switch them on in the account's settings in the dashboard. Reads keep working.

missing_permission

In the dashboard: your workspace role does not allow this. error.permission names the permission. Ask an owner or admin. Over MCP, search_api and describe_endpoint return it to a test key or to a workspace with no linked account: connect with a live key and link an account first.

dashboard_key_only

Only the dashboard runs a pending action, after a person approves it. API and OAuth keys create actions and read their status. An action from a key with auto-approve on runs when the key creates it.

session_only

Dashboard only. An account access token can do what you can do in a workspace, but not account security, invitations, OAuth consent or managing tokens. Sign in at betterfans.link and do it in the dashboard.

reauthentication_required

Dashboard only. Some changes need a sign in from the last 10 minutes: deleting a workspace or your account, changing your email, setting a first password and turning two-step verification on or off. Sign in again with your password or an email code, then retry.

email_not_verified

Dashboard only. A new dashboard account confirms its email before it opens a workspace. Enter the code emailed at sign up, or send a new one.

workspace_suspended

BetterFans Link suspended live calls for this workspace. Synced reads, test mode and the dashboard keep working, so nothing you stored is lost. Write to hello@betterfans.link to find out why and to have it lifted. Retrying does not help until it is lifted.

staff_only

Dashboard only. Only BetterFans Link staff can open the admin console. A workspace role, owner included, does not reach it.

staff_protected

Dashboard only. Staff accounts, and your own, cannot be banned or viewed as. Remove their staff role first.

impersonation_read_only

Dashboard only. BetterFans Link staff are viewing the dashboard as this person to help with a support request. That view is read only, so every change is refused until they stop viewing.

Not found

account_not_found

The account id is not linked to your workspace, your key is limited to other accounts, or a test key asked for an account that is not a sandbox creator. BetterFans Link answers 404, never 403, so it never reveals whether an account exists. List the accounts your key can use with GET /v1/accounts.

fan_not_found

Fan ids are user ids on the account's platform. Find the fan with GET /v1/accounts/{accountId}/fans?search= and use the id it returns.

chat_not_found

A chat id is the fan's id. Use a fan id from List fans or List chats.

action_not_found

Check the id, or list actions with GET /v1/actions.

link_not_found

Check the id, or create a new link with POST /v1/links.

route_not_found

The method and path match no route. Paths start with /v1. Compare yours with the API reference.

workspace_not_found

Dashboard only. The workspace does not exist or you are not a member. Pick a workspace you belong to.

resource_not_found

Something the request refers to does not exist. Check every id in the path.

user_not_found

Dashboard only. No person with this id or email has a BetterFans Link account. Check the address, or ask them to sign up first.

Conflict

idempotency_conflict

You reused an Idempotency-Key with a different body. One key stands for one intended action: use a new key for a new action. The same key with the same body returns the original action, so retries are safe.

action_not_pending

The action was already approved, rejected, run or it failed. Read its status with GET /v1/actions/{actionId}.

action_expired

Pending actions expire after 24 hours without a decision. Create the action again with a new Idempotency-Key.

link_not_ready

Dashboard only. The link is not at the step this request is for, for example a 2FA code sent before the platform asked for one, or a sign-in before the creator picked a platform. Reload the link's state and follow the step it shows.

last_owner

Dashboard only. A workspace always keeps at least one owner. Make another member an owner before you remove or demote this one.

owns_workspaces

Dashboard only. Deleting your account would leave a workspace with no owner. The message names each workspace you own alone. Make another member an owner of each one, or delete it, then delete your account.

two_factor_enabled

Dashboard only. Two-step verification is already on for your account. To move it to a new authenticator app, turn it off on the Account page, then set it up again.

two_factor_not_enabled

Dashboard only. Two-step verification is off, so there is nothing to turn off and no backup codes to replace. Turn it on from the Account page first.

subscription_exists

Dashboard only. The workspace already pays for a plan, so it cannot start a second subscription. Change the plan on the Billing page instead: the difference is prorated.

no_subscription

Dashboard only. The workspace is on the Free plan or its subscription ended, so there is nothing to change, cancel or resume. Choose a plan on the Billing page to start one.

subscription_active

Dashboard only. A workspace with a subscription that has not ended cannot be deleted, so nobody keeps paying for a workspace that is gone. An owner cancels it on the Billing page. The plan holds until the end of the period; delete the workspace after that.

checkout_unavailable

Dashboard only. Plans cannot be bought in the dashboard right now. Nothing was charged. Write to hello@betterfans.link and we will set the plan up for you.

plan_not_available

Dashboard only. The plan is not sold in the dashboard, for example Enterprise, which is quoted. Write to hello@betterfans.link for it, or pick a plan the Billing page offers.

last_admin

Dashboard only. BetterFans Link always keeps one staff admin. Make someone else an admin before removing the last one.

user_banned

Dashboard only. This person is banned, and this action needs them unbanned. Lift the ban first.

email_unverified

Dashboard only. Staff need a confirmed email. Ask the person to confirm their email, then try again.

account_in_use

Dashboard only. A Fansly account can be connected in one place at a time, and this one is already connected somewhere else. Remove it from the other workspace first, then link it again.

Account unavailable

account_unavailable

The platform is not accepting calls for this account. error.accountStatus is one of needs_relink, awaiting_2fa, awaiting_selfie, restricted or disconnected. Live reads, Call OnlyFans and Call Fansly stop until the account is healthy again, and approved actions cannot run. Reads without fresh=true keep working. Do not retry until the status changes: see account status for what fixes each one.

Rate limited

rate_limited

The key sent more requests than its rate limit allows. Wait the number of seconds in the Retry-After header, then retry. See rate limits.

Upstream

onlyfans_error

OnlyFans answered a live read with an error. Retry after a short wait. If it keeps failing, read the account with GET /v1/accounts/{accountId}: its status may have changed.

onlyfans_timeout

OnlyFans did not answer in time. Retry later, or leave out fresh=true to read synced data.

fansly_error

Fansly answered a live read with an error. Retry after a short wait. If it keeps failing, read the account with GET /v1/accounts/{accountId}: its status may have changed.

fansly_timeout

Fansly did not answer in time. Retry later, or leave out fresh=true to read synced data.

billing_provider_error

Dashboard only. The payment provider did not answer in time. Nothing was charged and the plan did not change. Retry in a minute.

Internal

internal_error

Something failed inside BetterFans Link. In test mode it comes back as 503 while the sandbox is briefly unavailable. Retry with a growing delay. If it keeps happening, send the requestId to hello@betterfans.link.