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

# Error handling

> Every API error is a parseable RFC 9457 problem document — built for both humans and AI agents to know what failed, whether to retry, and what to do next.

The API never returns HTML error pages or ad-hoc JSON to programmatic clients.
Every error is a [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem
document — a stable machine contract that tells a caller **what failed**,
**whether to retry**, and **what to do next**. This is what makes errors
agent-friendly: an AI client can branch on the fields without parsing prose.

## The shape

```jsonc theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 410 Gone
content-type: application/problem+json
cache-control: no-store
link: <https://onlyfanskit.dev/problems/account-disconnected>; rel="type"

{
  "type":      "https://onlyfanskit.dev/problems/account-disconnected",
  "title":     "Account session is no longer valid",
  "status":    410,
  "detail":    "Reconnect the account to continue.",
  "code":      "account-disconnected",
  "retryable": false
}
```

Core members `type`, `title`, and `status` are always present. `type` is a
stable URI you can branch on — it won't change once shipped.

## Agent extensions

When relevant, problems carry extra members so you can react without parsing
prose:

| Field                             | Meaning                                                          |
| --------------------------------- | ---------------------------------------------------------------- |
| `code`                            | Stable slug — matches the last segment of `type`.                |
| `retryable`                       | `true` if retrying after backoff may succeed.                    |
| `retryAfterSec`                   | Seconds to wait before retrying (pairs with `Retry-After`).      |
| `reason`                          | Quota / auth classification (`org_rpm`, `account_write_rpm`, …). |
| `limit`, `current`                | Present on quota problems.                                       |
| `upstreamCode`, `upstreamMessage` | The raw OnlyFans error, when relaying one.                       |

## Common statuses

| Status | When                                                                 |
| ------ | -------------------------------------------------------------------- |
| 400    | Invalid request, or OnlyFans rejected the credentials.               |
| 401    | Missing or invalid API key.                                          |
| 402    | Plan doesn't allow the action (e.g. minting extra keys).             |
| 403    | Missing scope, or a creator-only endpoint called from a fan account. |
| 404    | Account, attempt, or method not found.                               |
| 410    | Account session is no longer valid — reconnect the account.          |
| 412    | Reauthentication needs stored credentials the account doesn't have.  |
| 429    | Rate limit — see [Rate limiting](/platform/rate-limiting).           |
| 502    | A call to OnlyFans failed; see `detail` and `upstream*`.             |
| 503    | A required dependency isn't available — retry later.                 |

## Handling in the SDK

In the SDK, non-2xx responses throw `OnlyFansAPIError`. See
[Handling errors](/sdk/errors) for the pattern and what the common OnlyFans
responses mean.