> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ofauth.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understand V3 errors and decide what your app should do next.

V3 returns errors in two formats. The token and revoke endpoints use the OAuth format defined by RFC 6749. Everything under `/v3/access`, `/v3/vault-plus`, and `/v3/linked-accounts` uses the API error response.

## API error response

```json theme={null}
{
  "error": "linked_account_reconnect_required",
  "recovery": { "action": "reconnect_linked_account" },
  "requestId": "4f5c3f0e-8d7c-4ff5-9b7f-7d0d9e7c2a61"
}
```

| Field | Description |
| - | - |
| `error` | Stable machine-readable code. |
| `recovery.action` | What your app should do next. Use this value to choose how to handle the error. |
| `requestId` | Also sent as the `x-request-id` header. Quote it in support requests. |

## API error codes

| HTTP | `error` | `recovery.action` | Cause |
| - | - | - | - |
| 401 | `external_oauth_bearer_required` | `obtain_external_oauth_token` | No bearer token, or an API key header was sent. |
| 401 | `invalid_token` | `obtain_external_oauth_token` | The access token is expired, malformed, or not valid here. Refresh and retry. |
| 401 | `grant_revoked_or_expired` | `restart_authorization` | The permission linked to this token has ended. Run the authorization flow again. |
| 401 | `authorization_required` | `restart_authorization` | The authorization is not usable. Run the authorization flow again. |
| 401 | `linked_account_reconnect_required` | `reconnect_linked_account` | The account's OnlyFans session ended. The owner must reconnect. |
| 403 | `linked_account_required` | `select_linked_account` | Missing or malformed `x-linked-account-id`. |
| 403 | `linked_account_not_granted` | `grant_linked_account` | The account is not part of this authorization. |
| 404 | `linked_account_not_found` | `list_linked_accounts` | The account in the path is not part of this authorization (`/v3/linked-accounts/{id}` routes). |
| 403 | `linked_account_vault_plus_disabled` | `enable_linked_account_vault_plus` | Vault+ is off for this account. See [linked account settings](https://docs.ofauth.com/v3/api-reference/account/linked-accounts.md#linked-account-settings). |
| 403 | `vault_plus_disabled` | `enable_vault_plus` | Vault+ is off for this environment. |
| 403 | `missing_scope` | `request_additional_consent` | The operation needs a scope that is not in the token. Authorize again with the scope. |
| 403 | `additional_consent_required` | `request_additional_consent` | The token includes the scope, but the owner did not approve it for this account. Authorize again. |
| 403 | `integration_not_approved` | `complete_integration_approval` | Live is not approved for this integration. |
| 403 | `subscription_required` | `update_developer_plan` | The organization has no active Developer plan. |
| 403 | `integration_suspended` | `contact_integration_owner` | The integration or a required feature is unavailable. |
| 403 | `security_suspended` | `contact_integration_owner` | OFAuth suspended the integration for security reasons. |
| 403 | `client_deleted` | `contact_integration_owner` | The environment client was deleted. |
| 409 | `linked_account_settings_conflict` | `retry` | Another request changed these settings at the same time. Retry. |
| 409 | `linked_account_settings_fixed` | | Sandbox settings cannot change. |
| 429 | `quota_exhausted` | `retry_after_reset` | Test daily quota used up. `Retry-After` gives seconds until the UTC reset. |
| 429 | `rate_limited` | `retry` | Too many requests. Read `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. |
| 503 | `authorization_temporarily_unavailable` | `retry` | OFAuth could not validate the request right now. Retry with a longer wait after each failed attempt. |

Validation errors on request bodies and query parameters return `400` with the same JSON format and a descriptive `error`, such as `invalid_request`.

When OnlyFans rejects a request, the error is one of `provider_request_rejected` (`do_not_repeat` or `check_request`), `provider_resource_not_found` (`check_resource`), `linked_account_reconnect_required` (`reconnect_linked_account`), `rate_limited` (`retry`), or `transient_provider_failure` (`retry`).

## Recovery actions

| `recovery.action` | Your next step |
| - | - |
| `obtain_external_oauth_token` | Refresh the access token. If the refresh fails with `invalid_grant`, start authorization. |
| `restart_authorization` | Delete the stored refresh token and send the user through [Authorize](https://docs.ofauth.com/v3/api-reference/link/authorize.md). |
| `reconnect_linked_account` | Ask the owner to reconnect the account. Its id stays the same. You receive `linked_account.reconnected` when it works again. |
| `select_linked_account` | Send a valid `x-linked-account-id`. |
| `grant_linked_account` | Run authorization so the owner can share this account. |
| `list_linked_accounts` | Refresh your account list from `GET /v3/linked-accounts`. |
| `request_additional_consent` | Run authorization with the required scopes. |
| `enable_linked_account_vault_plus` | Turn Vault+ on for the account with `PATCH /v3/linked-accounts/{id}/settings`. |
| `enable_vault_plus` | Turn Vault+ on for the environment in the dashboard. |
| `retry_after_reset` | Wait `Retry-After` seconds. |
| `retry` | Retry with a longer wait after each failed attempt. |
| `complete_integration_approval` | Request Live approval from the dashboard. |
| `update_developer_plan` | Activate the Developer plan. |
| `contact_integration_owner` | Your app cannot fix this. Notify the integration owner. |
| `do_not_repeat` | OnlyFans refused the request. Do not retry it unchanged. |
| `check_request` | Fix the request before retrying. |
| `check_resource` | The OnlyFans resource does not exist. |

## OAuth endpoint errors

`POST /v3/link/token` and `POST /v3/link/revoke` return RFC 6749 bodies.

```json theme={null}
{
  "error": "invalid_grant",
  "error_description": "request rejected",
  "reason": "developer_plan_unavailable",
  "recovery": { "action": "contact_integration_owner" }
}
```

| HTTP | `error` | Cause |
| - | - | - |
| 400 | `invalid_request` | Missing, duplicate, or unsupported field; body is not form-encoded. |
| 400 | `unsupported_grant_type` | The `grant_type` is not `authorization_code` or `refresh_token`. |
| 401 | `invalid_client` | Bad Basic credentials, or the client is unavailable. |
| 400 | `invalid_grant` | The code or refresh token expired, was already used, or was revoked. The PKCE verifier or callback URL may not match. |
| 400 | `invalid_scope` | Unknown scope or a permission the user did not approve. |
| 400 | `invalid_target` | `resource` is not `https://api.ofauth.com/v3`, or the client is in the wrong environment for that user's approval. |
| 429 | `rate_limited` | Too many requests or failed client authentications. Wait for `Retry-After`. |
| 500 | `server_error` | Retry with a longer wait after each failed attempt. |

`reason` and `recovery` appear only when the integration is deleted, its plan is unavailable, or it is suspended (`client_deleted`, `developer_plan_unavailable`, `security_suspended`).

## Callback errors

The authorization redirect can return `error=access_denied` (user declined or cancelled) or `error=invalid_request` (the request expired or was malformed). Both include your original `state`.

## Handling pattern

The [SDKs](https://docs.ofauth.com/v3.md#official-sdks) expose API errors as exceptions with the error code, recovery action, and request ID. This TypeScript example uses the client from [SDK setup](https://docs.ofauth.com/v3/sdk/typescript.md). Retry rules are built into the SDK; follow [Handle failed requests](https://docs.ofauth.com/v3/reference/error-handling.md) when deciding what your app does next.

```typescript TypeScript SDK theme={null}
import { OFAuthAPIError } from "@ofauth/onlyfans-sdk"

try {
  const profile = await client.access.profile.get()
  console.log(profile.name)
} catch (error) {
  if (!(error instanceof OFAuthAPIError)) throw error
  console.error(error.code, error.requestId)
  switch (error.recoveryAction) {
    case "reconnect_linked_account":
      return promptReconnect(linkedAccountId)
    case "restart_authorization":
    case "grant_linked_account":
    case "request_additional_consent":
      return promptReauthorize(userId)
    default:
      throw error
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.