OnlyFans API Error Codes
OnlyFans API errors from ofapis all come back in one shape, so you can handle them with a single branch. This page lists the real codes the API returns, what triggers each, and how to react. Because billing is metered on success, a failed call doesn't cost a credit — an error is a free signal.
The error envelope
Success responses are wrapped in data; errors are wrapped in error:
{ "error": { "code": "OF_SESSION_EXPIRED", "message": "The OnlyFans session for account 42 is expired." } }
Branch on the HTTP status first, then on error.code for the specific case.
Codes
| Status | code |
Meaning | What to do |
|---|---|---|---|
| 400 | BAD_REQUEST |
Invalid body — e.g. blank list name, scheduledAt not in the future, empty userIds |
Fix the payload; don't retry as-is |
| 401 | UNAUTHENTICATED |
Missing or invalid API token | Check the Authorization: Bearer ofapis_sk_… header |
| 402 | INSUFFICIENT_CREDITS |
Out of credits for the period | Top up or wait for the monthly reset — see pricing |
| 403 | NO_ACTIVE_SUBSCRIPTION |
No active plan on the account | Start a plan |
| 404 | ACCOUNT_NOT_FOUND |
The accountId in the path isn't yours |
Use a linked account id |
| 413 | MEDIA_FILE_TOO_LARGE |
Upload over 50 MB | Compress or split the file |
| 415 | MEDIA_TYPE_NOT_SUPPORTED |
Unsupported file type | Use jpeg, png, webp or mp4 |
| 422 | ACCOUNT_NOT_ACTIVE |
The account isn't active | Re-check the account status |
| 424 | ACCOUNT_NOT_LINKED |
No OnlyFans account linked to this token | Link an account, then retry |
| 424 | OF_SESSION_EXPIRED / OF_AUTH_INVALID |
The stored OnlyFans session is expired/invalid | Re-link the account |
| 429 | RATE_LIMIT_EXCEEDED |
Too many requests | Back off for Retry-After seconds |
Handling in code
Three buckets cover almost everything:
- Retry with backoff —
429. Read theRetry-Afterheader (seconds) and theX-RateLimit-Resetepoch, then retry. See rate limits. - Re-link, then retry —
424(OF_SESSION_EXPIRED/ACCOUNT_NOT_LINKED). The account's session needs refreshing; surface a "reconnect" prompt. - Fix and stop —
400,413,415,404. These are your bug, not a transient one — don't loop.
r = requests.post(url, headers=H, json=body)
if r.status_code == 429:
time.sleep(int(r.headers.get("Retry-After", 30)))
elif r.status_code == 424:
reconnect(account_id) # session expired — re-link
elif not r.ok:
log.error(r.json()["error"]) # 4xx you must fix
else:
handle(r.json()["data"])
Rate-limit headers
Every response carries the current window so you can pace proactively rather than wait for a 429:
X-RateLimit-Limit— requests allowed in the windowX-RateLimit-Remaining— requests leftX-RateLimit-Reset— Unix epoch when it resetsRetry-After— on a429, seconds to wait
FAQ
Do failed API calls cost credits?
No. Credits are metered on success — an expired session, a validation error or a rate-limit rejection is never billed, so retrying safely doesn't run up cost.
What does a 424 error mean?
The token is valid but the OnlyFans account behind it needs attention — either nothing is linked (ACCOUNT_NOT_LINKED) or the session expired (OF_SESSION_EXPIRED). Re-link the account and retry.
How do I handle rate limiting?
On a 429, wait the number of seconds in the Retry-After header before retrying, and watch X-RateLimit-Remaining to slow down before you hit the wall. Details on the rate limits page.
Which errors should I retry?
Retry 429 after a backoff, and 424 after re-linking. Don't retry 400, 413, 415 or 404 unchanged — those mean the request itself needs fixing.