Error Handling

All API errors use a consistent two-field structure. Use the code field for programmatic handling — never parse the error string.

Error Response Format

Every error response has exactly two fields. The code is stable and machine-readable; the error message is human-readable and may change.

JSON

{
  "error": "Human-readable description of what went wrong.",
  "code":  "MACHINE_READABLE_CODE"
}

Always switch on code, not error

The error message text can change between releases. The code field is stable — use it in your switch/case logic.

HTTP Status Codes

200OKRequest succeeded — credits deducted

400Bad RequestInvalid request parameters or body

401UnauthorizedMissing or invalid API key

402Payment RequiredNo active subscription, or insufficient credits

429Too Many RequestsRate limit exceeded — slow down

500Internal Server ErrorUnexpected gateway error

502Bad GatewayOnlyFans returned an error for this request

Common Error Examples

401 — Invalid API Key

JSON

HTTP 401 Unauthorized

{
  "error": "The provided API key is invalid or has been revoked.",
  "code": "INVALID_API_KEY"
}

402 — No Active Subscription

JSON

HTTP 402 Payment Required

{
  "error": "Your organization does not have an active subscription.",
  "code": "NO_SUBSCRIPTION"
}

402 — Insufficient Credits

JSON

HTTP 402 Payment Required

{
  "error": "Not enough credits to complete this request.",
  "code": "INSUFFICIENT_CREDITS"
}

429 — Rate Limit Exceeded

JSON

HTTP 429 Too Many Requests

{
  "error": "Rate limit exceeded. Slow down and try again.",
  "code": "RATE_LIMIT_EXCEEDED"
}

502 — OnlyFans API Error

JSON

HTTP 502 Bad Gateway

{
  "error": "OnlyFans returned an error for this request.",
  "code": "OF_API_ERROR"
}

Check the model's session

A 502 usually means the model's OnlyFans session has expired or the account was logged out. Go to the dashboard and reconnect the model.

500 — Server Error

JSON

HTTP 500 Internal Server Error

{
  "error": "An unexpected error occurred.",
  "code": "INTERNAL_ERROR"
}

Error Code Reference

All machine-readable error codes you may encounter when using proxy endpoints.

Code	Status	Description
`NO_API_KEY`	401	The X-API-Key header is missing from the request.
`INVALID_API_KEY`	401	The API key is invalid or has been revoked.
`NO_SUBSCRIPTION`	402	The organization does not have an active subscription.
`INSUFFICIENT_CREDITS`	402	Credit balance is too low for this endpoint's cost.
`RATE_LIMIT_EXCEEDED`	429	Too many requests. Check your plan's rate limit and retry.
`OF_API_ERROR`	502	OnlyFans returned an error. Check the model's session status from the dashboard.
`INTERNAL_ERROR`	500	Unexpected server error. Contact support if it persists.

Best Practices

Switch on code, not error messageThe error field is human-readable and can change. The code field is stable — always use it in your logic.

Retry only on 429 and 500/502401 and 402 errors won't resolve by retrying. Fix the root cause first (invalid key, no credits, no subscription).

For 429 — back off before retryingWait a few seconds before retrying after a rate limit error. Hammering the API immediately will just trigger more 429s.

For 502 — reconnect the modelA 502 usually means the model's OnlyFans session expired. Go to the dashboard and reconnect it.

Monitor your credit balanceCheck your remaining credits from the dashboard. Set up alerts before you run out to avoid interrupted service.

PreviousRate LimitingLimits, headers, and retry logic