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

# Error Handling

> Explore errors that the API could potentially show and how to handle them

## Overview

The Cevoid API uses standard HTTP status codes to indicate the success or failure of your requests. Understanding these codes will help you build robust applications that can properly handle different scenarios.

## HTTP Status Codes

### Success

* **`200`** - Successful response: The request was processed successfully

### Client Errors

* **`400`** - Bad request: There was an error in your request (client-side error)
* **`401`** - Unauthorized: Invalid or missing authentication credentials
* **`403`** - Forbidden: The request is not allowed (insufficient permissions)
* **`404`** - Not found: The requested resource does not exist

### Server Errors

* **`402`** - Request failed: Valid parameters were provided, but the request failed
* **`500`** - Internal server error: An error occurred on Cevoid's servers

***

## Error Types

The Cevoid API returns errors with specific types to help you understand what went wrong:

### `invalid_request`

Issues with your request (most common):

* Missing required parameters
* Invalid parameter values
* Malformed request body
* Authentication problems

### `api_error`

Issues on Cevoid's side (rare):

* Internal server problems
* Service temporarily unavailable
* Database connectivity issues

***

## Error Response Format

When an error occurs, the API returns a structured error response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "invalid_request",
  "message": "The 'limit' parameter must be between 1 and 25",
  "documentation_url": "https://docs.cevoid.com/api-reference/errors"
}
```

### Response Fields

* **`type`**: The error category (`invalid_request` or `api_error`)
* **`message`**: Human-readable description of the error
* **`documentation_url`**: Link to relevant documentation

***

## Common Error Scenarios

### Authentication Errors (401)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "invalid_request",
  "message": "Invalid API key provided",
  "documentation_url": "https://docs.cevoid.com/api-reference/authentication"
}
```

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

### Resource Not Found (404)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "invalid_request",
  "message": "Post with ID 'abc123' not found",
  "documentation_url": "https://docs.cevoid.com/api-reference/errors"
}
```

**Solution**: Check that the resource ID exists and you have permission to access it.

### Invalid Parameters (400)

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "invalid_request",
  "message": "The 'limit' parameter must be between 1 and 25",
  "documentation_url": "https://docs.cevoid.com/api-reference/pagination"
}
```

**Solution**: Review the API documentation for correct parameter values and formats.

***

## Error Handling Best Practices

### 1. Always Check Status Codes

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
const response = await fetch('https://api.cevoid.com/v1/posts', {
  headers: {
    'x-api-key': 'your-api-key'
  }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`API Error (${response.status}):`, error.message);
  return;
}

const data = await response.json();
```

### 2. Handle Different Error Types

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
try {
  const response = await makeApiRequest();
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.type) {
      case 'invalid_request':
        // Handle client-side errors (fix request)
        handleClientError(error);
        break;
      case 'api_error':
        // Handle server-side errors (retry or alert user)
        handleServerError(error);
        break;
    }
  }
} catch (networkError) {
  // Handle network connectivity issues
  handleNetworkError(networkError);
}
```

### 3. Implement Retry Logic

<Tip>
  For `api_error` types (500, 502 status codes), implement exponential backoff retry logic as these are typically temporary server issues.
</Tip>

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function retryRequest(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok || response.status < 500) {
        return response; // Success or client error (don't retry)
      }
      
      if (attempt === maxRetries) {
        throw new Error(`Request failed after ${maxRetries} attempts`);
      }
      
      // Wait before retrying (exponential backoff)
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, attempt - 1)));
      
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}
```

### 4. Log Errors for Debugging

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
if (!response.ok) {
  const error = await response.json();
  
  // Log the error with context
  console.error('API Request Failed:', {
    status: response.status,
    type: error.type,
    message: error.message,
    requestUrl: response.url,
    timestamp: new Date().toISOString()
  });
}
```

<Warning>
  Never expose API keys or sensitive information in error logs or user-facing error messages.
</Warning>