Error Handling

Overview

The OFAuth API uses standard HTTP status codes with structured JSON error responses to provide clear, actionable feedback when things go wrong.

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": "Human-readable error message",
  "type": "ERROR_TYPE",
  "requestId": "req_abc123",
  "actionRequired": "refresh_session"
}

Error Response Fields

Field	Type	Description
`error`	string	Human-readable error message for developers
`type`	string	Machine-readable error type for programmatic handling
`requestId`	string	Unique request identifier for debugging and support
`actionRequired`	string	Optional hint for how to resolve the error

HTTP Status Codes

Success Codes

Code	Description	When Used
`200`	OK	Request successful, data returned
`201`	Created	Resource successfully created
`204`	No Content	Request successful, no data to return

Client Error Codes

Code	Description	Action Required
`400`	Bad request	Fix request format/data
`401`	Session expired or invalid	Re-authenticate user
`404`	Route or resource not found	Check endpoint URL
`429`	Rate limit exceeded	Wait and retry

Server Error Codes

Code	Description	Action Required
`500`	Unknown error	Retry or contact support
`502`	Proxy error	Retry after delay
`503`	Network error	Retry after delay

Error Types

The type field in error responses will be one of the following:

Type	HTTP Status	Description	Action Required
`UNAUTHORIZED`	401	Missing or invalid API key	Check API key
`SESSION_NOT_PROVIDED`	401	Connection not found or missing session data	Re-authenticate user via Link
`SESSION_EXPIRED`	401	User session has expired	Re-authenticate user via Link
`FORBIDDEN`	403	Insufficient permissions	Check connection permissions
`RULES_OUTDATED`	401	Dynamic rules need updating	Retry—OFAuth handles this automatically
`BAD_REQUEST`	400	Invalid request parameters	Fix request format/data
`RESOURCE_NOT_FOUND`	404	Requested resource not found	Check resource ID
`ROUTE_NOT_FOUND`	404	Endpoint path not found	Check endpoint URL
`RATE_LIMIT_EXCEEDED`	429	Request rate limit exceeded	Wait and retry with backoff
`UPLOAD_ERROR`	502	Media upload failed	Retry upload
`UNKNOWN_ERROR`	500/503	Unexpected or temporary error	Retry or contact support

Action Required Hints

Some errors include an actionRequired field suggesting how to resolve the issue:

Action	Description
`relink_connection`	Connection expired—user needs to re-authenticate via Link
`verify_identity`	ID verification required—prompt user to complete verification on OnlyFans
`refresh_rules`	Dynamic rules are outdated (retry automatically)
`try_again`	Transient error—retry the request

Rate Limiting

When you hit a rate limit, the response includes:

HTTP Status: 429
Retry-After header: Seconds to wait before retrying

{
  "error": "Rate limit exceeded, please wait a few seconds before trying again",
  "type": "RATE_LIMIT_EXCEEDED",
  "requestId": "req_abc123"
}

Handling Rate Limits

Check for 429 status code
Read the Retry-After header (defaults to 60 seconds if missing)
Wait the specified duration before retrying
Implement exponential backoff for repeated failures

Common Error Scenarios

Session Expired

When a user’s OnlyFans session expires:

{
  "error": "Connection expired",
  "type": "SESSION_EXPIRED",
  "actionRequired": "relink_connection",
  "requestId": "req_abc123"
}

Resolution: Redirect the user through the Link flow to re-authenticate.

Connection Not Found

When a connection ID doesn’t exist or has no session data:

{
  "error": "Connection not found",
  "type": "SESSION_NOT_PROVIDED",
  "requestId": "req_abc123"
}

Resolution: The connection may have been deleted or never completed. Create a new Link session for the user.

Service Unavailable

When there’s a temporary issue:

{
  "error": "Service temporarily unavailable",
  "type": "UNKNOWN_ERROR",
  "actionRequired": "try_again",
  "requestId": "req_abc123"
}

Resolution: Retry the request after a short delay. These errors are typically transient.

Error Handling Best Practices

Check the type field

Branch on the type field for programmatic handling, not the error message

Log requestId

Include requestId in logs and support requests for debugging

Handle session errors

Watch for SESSION_EXPIRED and SESSION_NOT_PROVIDED to trigger re-auth flows

Implement retries

Use exponential backoff for PROXY_ERROR, NETWORK_ERROR, and rate limits

Example Error Handler

async function handleOFAuthRequest(response: Response) {
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.type) {
      case 'SESSION_EXPIRED':
      case 'SESSION_NOT_PROVIDED':
        // Redirect user to re-authenticate
        return redirectToLink(userId);
      
      case 'RATE_LIMIT_EXCEEDED':
        const retryAfter = response.headers.get('Retry-After') || '60';
        await sleep(parseInt(retryAfter) * 1000);
        return retry();
      
      case 'PROXY_ERROR':
      case 'NETWORK_ERROR':
        // Retry with backoff
        await sleep(1000);
        return retry();
      
      default:
        console.error('OFAuth error:', error.type, error.error, error.requestId);
        throw new Error(error.error);
    }
  }
  
  return response.json();
}

Next Steps

Rate Limiting

Token bucket system and backoff strategies

Access API

Using the Access API

System Webhook Events

Get notified of connection status changes

Introduction

Setup

Reference

Advanced

Error Handling

Overview

Error Response Format

Error Response Fields

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Types

Action Required Hints

Rate Limiting

Handling Rate Limits

Common Error Scenarios

Session Expired

Connection Not Found

Service Unavailable

Error Handling Best Practices

Check the type field

Log requestId

Handle session errors

Implement retries

Example Error Handler

Next Steps

Rate Limiting

Access API

System Webhook Events

​Overview

​Error Response Format

​Error Response Fields

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Error Types

​Action Required Hints

​Rate Limiting

​Handling Rate Limits

​Common Error Scenarios

​Session Expired

​Connection Not Found

​Service Unavailable

​Error Handling Best Practices

Check the type field

Log requestId

Handle session errors

Implement retries

​Example Error Handler

​Next Steps

Rate Limiting

Access API

System Webhook Events

Overview

Error Response Format

Error Response Fields

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Types

Action Required Hints

Rate Limiting

Handling Rate Limits

Common Error Scenarios

Session Expired

Connection Not Found

Service Unavailable

Error Handling Best Practices

Example Error Handler

Next Steps