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

# Error Handling

> Understand Doozy API error responses and how to handle them

<Warning>
  The Doozy API is currently in **closed beta**. To request access, please email [hello@doozy.live](mailto:hello@doozy.live).
</Warning>

## Error Response Format

When an error occurs, the API returns a JSON response with an `error` object containing a `code` and `message`:

```json theme={null}
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid API key."
  }
}
```

## Error Codes

| HTTP Status | Error Code       | Description                                                         |
| ----------- | ---------------- | ------------------------------------------------------------------- |
| `400`       | `bad_request`    | The request was malformed or missing required parameters            |
| `401`       | `invalid_key`    | The API key is missing, invalid, or has been revoked                |
| `403`       | `forbidden`      | The API key doesn't have permission to access this resource         |
| `404`       | `not_found`      | The requested resource doesn't exist or you don't have access to it |
| `429`       | `rate_limited`   | You've exceeded the rate limit of 1,000 requests per hour           |
| `500`       | `internal_error` | An unexpected error occurred on our servers                         |

## Handling Errors

### Invalid API Key (401)

```json theme={null}
{
  "error": {
    "code": "invalid_key",
    "message": "Invalid API key."
  }
}
```

**Causes:**

* The API key is missing from the request
* The API key format is incorrect
* The API key has been revoked or deleted

**Solution:** Verify your API key is correct and included in the `x-api-key` header.

### Forbidden (403)

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "You do not have permission to access this resource."
  }
}
```

**Causes:**

* Your user account doesn't have permission to access this resource
* You were removed as an admin/manager from the quiz or survey

**Solution:** Check your permissions in the Doozy dashboard. If you were recently removed from a resource, you'll need to be re-added to regain API access.

### Not Found (404)

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Resource not found."
  }
}
```

**Causes:**

* The resource ID is incorrect
* The resource has been deleted
* You don't have access to view this resource

**Solution:** Verify the resource ID and your permissions.

### Rate Limited (429)

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Please try again later."
  }
}
```

**Causes:**

* You've exceeded 1,000 requests per hour

**Solution:** Wait before making additional requests. Implement exponential backoff in your integration:

```javascript theme={null}
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      // Wait 60 seconds before retrying
      const waitTime = 60 * 1000 * Math.pow(2, attempt);
      await new Promise(resolve => setTimeout(resolve, waitTime));
      continue;
    }
    
    return response;
  }
  throw new Error('Max retries exceeded');
}
```

<Tip>
  If you consistently hit rate limits, consider caching responses or reducing request frequency. Contact [hello@doozy.live](mailto:hello@doozy.live) if you need higher limits.
</Tip>

### Internal Error (500)

```json theme={null}
{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred."
  }
}
```

**Causes:**

* An unexpected error on our servers

**Solution:** Retry the request after a short delay. If the issue persists, contact [support@doozy.live](mailto:support@doozy.live).