Errors

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

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 only reads. To send, take back or change anything, create an action instead; a person approves it before it runs.

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.

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 an action, after a person approves it. API and OAuth keys create actions and read their status.

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 OnlyFans user ids. 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.

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 OnlyFans asked for one. 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.

Account unavailable

account_unavailable

OnlyFans is not accepting calls for this account. error.accountStatus is one of needs_relink, awaiting_2fa, awaiting_selfie, restricted or disconnected. Live reads and Call OnlyFans 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.

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.