Errors

Error Response Format

All Databuddy API errors follow a consistent JSON structure:

{
  "success": false,
  "error": "Human-readable error message",
  "code": "ERROR_CODE",
  "requestId": "req_abc123",
  "details": [
    {
      "field": "fieldName",
      "message": "Detailed error message",
      "suggestion": "How to fix the error"
    }
  ]
}

success

boolean

Always false for error responses

error

string

Human-readable error message describing what went wrong

code

string

Machine-readable error code for programmatic handling

requestId

string

Unique identifier for the request. Include this when contacting support.

details

array

Array of detailed error information, typically for validation errors

HTTP Status Codes

Databuddy uses standard HTTP status codes:

200

Request succeeded

400

Bad Request

Invalid request parameters or malformed data

401

Unauthorized

Missing or invalid authentication credentials

403

Forbidden

Authenticated but lacking required permissions

404

Not Found

Requested resource does not exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error (contact support if persistent)

Error Codes

Authentication Errors

AUTH_REQUIRED

Authentication is required but no credentials were providedSolution: Include an API key in the x-api-key header or Authorization header

INVALID_API_KEY

The provided API key is invalid, expired, or revokedSolution: Verify your API key is correct and hasn’t been revoked. Create a new key if needed.

ACCESS_DENIED

Authenticated but the API key lacks required scopes or permissionsSolution: Ensure your API key has the necessary scopes (e.g., read:data for queries)

Validation Errors

VALIDATION_ERROR

One or more request parameters are invalidDetails: Check the details array for field-specific errorsExample:

{
  "success": false,
  "error": "Invalid date format",
  "code": "VALIDATION_ERROR",
  "requestId": "req_abc123",
  "details": [
    {
      "field": "startDate",
      "message": "Invalid date: 2024-13-01. Could not parse as a valid date",
      "suggestion": "Use YYYY-MM-DD format"
    }
  ]
}

MISSING_PARAMETER

A required parameter is missing from the requestSolution: Check the endpoint documentation for required parameters

MISSING_PROJECT_ID

No project identifier provided (website_id, schedule_id, link_id, or organization_id)Solution: Include a project identifier in the query string

MISSING_WEBSITE_ID

The website_id parameter is required but was not providedSolution: Add ?website_id=your_website_id to the request URL

Resource Errors

NOT_FOUND

The requested resource does not existSolution: Verify the resource ID is correct and the resource hasn’t been deleted

UNAUTHORIZED

Not authorized to access this resourceSolution: Verify you have access to the organization or website

FORBIDDEN

Access to this resource is forbiddenSolution: Check that your API key or user account has the required permissions

CONFLICT

The request conflicts with the current state of the resourceSolution: Check if the resource already exists or has been modified

Rate Limit Errors

RATE_LIMIT_EXCEEDED

Too many requests in a short periodResponse includes:

limit: The rate limit that was exceeded
remaining: Remaining requests (0)
reset: When the limit resets
retryAfter: Seconds to wait before retrying

Solution: Wait for the rate limit to reset or implement exponential backoffExample:

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later.",
  "code": "RATE_LIMIT_EXCEEDED",
  "limit": 1000,
  "remaining": 0,
  "reset": "2024-01-01T12:00:00.000Z",
  "retryAfter": 45
}

Query Errors

QUERY_ERROR

The query could not be executedSolution: Check query syntax, filters, and parameters

COMPILATION_ERROR

The query could not be compiledSolution: Verify query structure matches expected format

UNKNOWN_QUERY_TYPE

The specified query type does not existSolution: Use /v1/query/types to list valid query typesExample:

{
  "field": "parameters[0]",
  "message": "Unknown query type: traffics",
  "suggestion": "Did you mean 'traffic'?"
}

INVALID_DATE_PRESET

The specified date preset is not validSolution: Use one of: today, yesterday, last7days, last30days, thisMonth, lastMonth, thisYear

Server Errors

INTERNAL_SERVER_ERROR

An unexpected error occurred on the serverSolution: Retry the request. If the error persists, contact support with the requestId

SERVICE_UNAVAILABLE

The service is temporarily unavailableSolution: Retry with exponential backoff

Handling Errors

Error Handling Best Practices

async function safeAPICall(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    
    if (!data.success) {
      // Handle API error
      switch (data.code) {
        case 'AUTH_REQUIRED':
        case 'INVALID_API_KEY':
          console.error('Authentication failed:', data.error);
          // Redirect to login or refresh credentials
          break;
          
        case 'ACCESS_DENIED':
          console.error('Permission denied:', data.error);
          // Show permission error to user
          break;
          
        case 'RATE_LIMIT_EXCEEDED':
          console.warn('Rate limited. Retrying after', data.retryAfter, 'seconds');
          // Implement retry logic
          await new Promise(resolve => setTimeout(resolve, data.retryAfter * 1000));
          return safeAPICall(url, options); // Retry
          
        case 'VALIDATION_ERROR':
          console.error('Validation failed:', data.details);
          // Display field-specific errors to user
          break;
          
        case 'NOT_FOUND':
          console.error('Resource not found:', data.error);
          break;
          
        case 'INTERNAL_SERVER_ERROR':
          console.error('Server error. Request ID:', data.requestId);
          // Log for monitoring, retry later
          break;
          
        default:
          console.error('API error:', data.error, data.code);
      }
      
      throw new Error(data.error);
    }
    
    return data;
  } catch (error) {
    if (error instanceof TypeError) {
      // Network error
      console.error('Network error:', error.message);
    } else {
      // Re-throw API errors
      throw error;
    }
  }
}

TypeScript Error Types

interface DatabuddyError {
  success: false;
  error: string;
  code: ErrorCode;
  requestId?: string;
  details?: ValidationError[];
}

interface ValidationError {
  field: string;
  message: string;
  suggestion?: string;
}

type ErrorCode =
  | 'AUTH_REQUIRED'
  | 'INVALID_API_KEY'
  | 'ACCESS_DENIED'
  | 'VALIDATION_ERROR'
  | 'NOT_FOUND'
  | 'RATE_LIMIT_EXCEEDED'
  | 'QUERY_ERROR'
  | 'INTERNAL_SERVER_ERROR';

function isDatabuddyError(data: unknown): data is DatabuddyError {
  return (
    typeof data === 'object' &&
    data !== null &&
    'success' in data &&
    data.success === false
  );
}

Validation Error Handling

Validation errors include helpful suggestions:

const response = await fetch('https://api.databuddy.cc/v1/query', {
  method: 'POST',
  headers: { 'x-api-key': API_KEY },
  body: JSON.stringify({
    website_id: 'website_123',
    parameters: ['traffics'], // Typo
    startDate: '2024-01-01',
    endDate: '2024-01-31',
  }),
});

const data = await response.json();
// {
//   "success": false,
//   "error": "Unknown query type: traffics. Did you mean 'traffic'?",
//   "code": "VALIDATION_ERROR",
//   "details": [{
//     "field": "parameters[0]",
//     "message": "Unknown query type: traffics",
//     "suggestion": "Did you mean 'traffic'?"
//   }]
// }

if (data.details) {
  data.details.forEach(detail => {
    console.error(`${detail.field}: ${detail.message}`);
    if (detail.suggestion) {
      console.log(`Suggestion: ${detail.suggestion}`);
    }
  });
}

Debugging Tips

1. Use Request IDs

Every response includes a requestId. Save these for debugging:

const data = await queryAPI(params);
console.log('Request ID:', data.requestId);
// Request ID: req_a1b2c3d4e5f6g7h8

2. Enable Detailed Logging

const DEBUG = true;

if (DEBUG) {
  console.log('Request:', {
    url,
    method: 'POST',
    headers: { ...headers, 'x-api-key': '[REDACTED]' },
    body: JSON.stringify(params, null, 2),
  });
}

const response = await fetch(url, options);
const data = await response.json();

if (DEBUG) {
  console.log('Response:', {
    status: response.status,
    headers: Object.fromEntries(response.headers.entries()),
    body: data,
  });
}

3. Check Query Types

List available query types:

curl https://api.databuddy.cc/v1/query/types \
  -H "x-api-key: dbdy_your_api_key"

4. Validate Dates

Use YYYY-MM-DD format or ISO 8601:

// Good
startDate: '2024-01-01'
startDate: '2024-01-01T00:00:00.000Z'

// Bad
startDate: '01/01/2024'
startDate: '2024-13-01' // Invalid month

Common Error Scenarios

Scenario 1: Invalid API Key

Request:

curl https://api.databuddy.cc/v1/query \
  -H "x-api-key: invalid_key"

Response:

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED",
  "requestId": "req_abc123"
}

Solution: Verify your API key format and validity.

Scenario 2: Missing Required Scope

Request: API key with only write:links scope trying to query analytics Response:

{
  "success": false,
  "error": "Access denied to this website",
  "code": "ACCESS_DENIED",
  "requestId": "req_abc123"
}

Solution: Add read:data scope to your API key.

Scenario 3: Validation Error

Request:

{
  "website_id": "website_123",
  "parameters": ["traffics"],
  "preset": "last7day"
}

Response:

{
  "success": false,
  "error": "Unknown query type: traffics. Did you mean 'traffic'?",
  "code": "VALIDATION_ERROR",
  "requestId": "req_abc123",
  "details": [
    {
      "field": "parameters[0]",
      "message": "Unknown query type: traffics",
      "suggestion": "Did you mean 'traffic'?"
    },
    {
      "field": "preset",
      "message": "Invalid date preset: last7day",
      "suggestion": "Did you mean 'last7days'?"
    }
  ]
}

Solution: Fix typos in parameters and preset names.

Getting Help

If you encounter persistent errors:

Check the documentation for the specific endpoint
Review error details in the response
Test with the interactive API docs at https://api.databuddy.cc/
Contact support with your requestId

Overview

Events API

Analytics API

Projects API

Links API

Uptime API

SDK Reference

Error Response Format

HTTP Status Codes

Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limit Errors

Query Errors

Server Errors

Handling Errors

Error Handling Best Practices

TypeScript Error Types

Validation Error Handling

Debugging Tips

1. Use Request IDs

2. Enable Detailed Logging

3. Check Query Types

4. Validate Dates

Common Error Scenarios

Scenario 1: Invalid API Key

Scenario 2: Missing Required Scope

Scenario 3: Validation Error

Getting Help

Build docs developers (and LLMs) love

Overview

Events API

Analytics API

Projects API

Links API

Uptime API

SDK Reference

​Error Response Format

​HTTP Status Codes

​Error Codes

​Authentication Errors

​Validation Errors

​Resource Errors

​Rate Limit Errors

​Query Errors

​Server Errors

​Handling Errors

​Error Handling Best Practices

​TypeScript Error Types

​Validation Error Handling

​Debugging Tips

​1. Use Request IDs

​2. Enable Detailed Logging

​3. Check Query Types

​4. Validate Dates

​Common Error Scenarios

​Scenario 1: Invalid API Key

​Scenario 2: Missing Required Scope

​Scenario 3: Validation Error

​Getting Help

Build docs developers (and LLMs) love

Error Response Format

HTTP Status Codes

Error Codes

Authentication Errors

Validation Errors

Resource Errors

Rate Limit Errors

Query Errors

Server Errors

Handling Errors

Error Handling Best Practices

TypeScript Error Types

Validation Error Handling

Debugging Tips

1. Use Request IDs

2. Enable Detailed Logging

3. Check Query Types

4. Validate Dates

Common Error Scenarios

Scenario 1: Invalid API Key

Scenario 2: Missing Required Scope

Scenario 3: Validation Error

Getting Help