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

# Error Handling

> Error codes, response formats, and debugging strategies for the OFAuth API

## 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:

```json theme={null}
{
  "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

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

### Handling Rate Limits

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

***

## Common Error Scenarios

### Session Expired

When a user's OnlyFans session expires:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Check the type field" icon="code">
    Branch on the `type` field for programmatic handling, not the error message
  </Card>

  <Card title="Log requestId" icon="file-text">
    Include `requestId` in logs and support requests for debugging
  </Card>

  <Card title="Handle session errors" icon="user">
    Watch for `SESSION_EXPIRED` and `SESSION_NOT_PROVIDED` to trigger re-auth flows
  </Card>

  <Card title="Implement retries" icon="rotate">
    Use exponential backoff for `PROXY_ERROR`, `NETWORK_ERROR`, and rate limits
  </Card>
</CardGroup>

### Example Error Handler

```typescript theme={null}
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

<CardGroup cols={3}>
  <Card title="Rate Limiting" icon="gauge" href="/reference/rate-limiting">
    Token bucket system and backoff strategies
  </Card>

  <Card title="Access API" icon="key" href="/api-reference/access/overview">
    Using the Access API
  </Card>

  <Card title="System Webhook Events" icon="bell" href="/api-reference/system-webhook-events/overview">
    Get notified of connection status changes
  </Card>
</CardGroup>