Error Handling

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.

Introduction

Core Concepts

Endpoints

Error Handling

Overview

HTTP Status Codes

Success

Client Errors

Server Errors

Error Types

`invalid_request`

`api_error`

Error Response Format

Response Fields

Common Error Scenarios

Authentication Errors (401)

Resource Not Found (404)

Invalid Parameters (400)

Error Handling Best Practices

1. Always Check Status Codes

2. Handle Different Error Types

3. Implement Retry Logic

4. Log Errors for Debugging

​Overview

​HTTP Status Codes

​Success

​Client Errors

​Server Errors

​Error Types

​invalid_request

​api_error

​Error Response Format

​Response Fields

​Common Error Scenarios

​Authentication Errors (401)

​Resource Not Found (404)

​Invalid Parameters (400)

​Error Handling Best Practices

​1. Always Check Status Codes

​2. Handle Different Error Types

​3. Implement Retry Logic

​4. Log Errors for Debugging

Overview

HTTP Status Codes

Success

Client Errors

Server Errors

Error Types

`invalid_request`

`api_error`

Error Response Format

Response Fields

Common Error Scenarios

Authentication Errors (401)

Resource Not Found (404)

Invalid Parameters (400)

Error Handling Best Practices

1. Always Check Status Codes

2. Handle Different Error Types

3. Implement Retry Logic

4. Log Errors for Debugging