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

# Error Codes

> Common API error codes and how to handle them

## Overview

The ReferralLoop API uses standard HTTP status codes to indicate success or failure. This guide explains common error codes and how to handle them.

## Error Response Format

All error responses follow this format:

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

Some errors may include additional fields:

```json theme={null}
{
  "error": "Email already exists on this waitlist",
  "signup": {
    "id": "...",
    "position": 1,
    "referral_code": "ABC123"
  }
}
```

## HTTP Status Codes

### 400 Bad Request

The request was malformed or contained invalid parameters.

**Common causes:**

* Missing required fields
* Invalid data types
* Invalid parameter values

**Example:**

```json theme={null}
{
  "error": "Email is required"
}
```

### 401 Unauthorized

The API key is missing, invalid, or expired.

**Common causes:**

* Missing `Authorization` header
* Invalid API key format
* Expired or revoked API key

**Example:**

```json theme={null}
{
  "error": "Invalid API key"
}
```

### 403 Forbidden

The request is valid, but the action is not allowed.

**Common causes:**

* Free plan attempting to use API (API access requires paid plan)
* Insufficient permissions

**Example:**

```json theme={null}
{
  "error": "API access requires a paid subscription",
  "message": "Upgrade your plan to use the API",
  "upgrade_url": "https://www.referralloop.dev/dashboard/billing"
}
```

### 404 Not Found

The requested resource doesn't exist.

**Common causes:**

* Invalid waitlist ID
* Invalid signup ID
* Resource was deleted

**Example:**

```json theme={null}
{
  "error": "Waitlist not found"
}
```

### 409 Conflict

The request conflicts with the current state of the resource.

**Common causes:**

* Email already exists on waitlist
* Duplicate resource creation

**Example:**

```json theme={null}
{
  "error": "Email already exists on this waitlist",
  "signup": {
    "id": "789e0123-e89b-12d3-a456-426614174000",
    "position": 1,
    "referral_code": "ABC123"
  }
}
```

### 429 Too Many Requests

The rate limit has been exceeded.

**Example:**

```json theme={null}
{
  "error": "Rate limit exceeded",
  "limit": 1000,
  "reset_at": "2024-01-15T11:00:00Z"
}
```

See [Rate Limits](essentials/rate-limit) for more information.

### 500 Internal Server Error

An unexpected error occurred on the server.

**What to do:**

* Retry the request after a short delay
* If the problem persists, contact support

**Example:**

```json theme={null}
{
  "error": "Failed to fetch waitlists"
}
```

## Error Handling Best Practices

1. **Always check the status code** before processing the response
2. **Read the error message** to understand what went wrong
3. **Implement retry logic** for 5xx errors with exponential backoff
4. **Handle rate limits** by checking the `X-RateLimit-Remaining` header
5. **Log errors** for debugging and monitoring

## Example Error Handling

```javascript theme={null}
try {
  const response = await fetch(
    "https://www.referralloop.dev/api/v1/waitlists",
    {
      headers: {
        Authorization: `Bearer ${apiKey}`,
      },
    }
  );

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        console.error("Invalid API key");
        break;
      case 429:
        console.error("Rate limit exceeded");
        const resetAt = response.headers.get("X-RateLimit-Reset");
        console.error(`Retry after: ${resetAt}`);
        break;
      default:
        console.error("API error:", error.error);
    }

    throw new Error(error.error);
  }

  const data = await response.json();
  return data;
} catch (error) {
  console.error("Request failed:", error);
  throw error;
}
```