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:

{
  "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)

{
  "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)

{
  "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)

{
  "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

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

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

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

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

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()
  });
}

Never expose API keys or sensitive information in error logs or user-facing error messages.