Error handling - onlyfanskit

The API never returns HTML error pages or ad-hoc JSON to programmatic clients. Every error is a RFC 9457 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

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.
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 for the pattern and what the common OnlyFans responses mean.