Error Handling

All API errors follow a consistent format with clear error codes, messages, and request IDs for debugging.

Error Response Format

{
"success": false,
"error": "Human-readable error message",
"code": "ERROR_CODE",
"requestId": "req_abc123def456"
}

Validation Errors

Validation errors include detailed field-level information:

{
"success": false,
"error": "Unknown query type: summry. Did you mean 'summary'?",
"code": "VALIDATION_ERROR",
"requestId": "req_abc123def456",
"details": [
  {
    "field": "parameters[0]",
    "message": "Unknown query type: summry",
    "suggestion": "Did you mean 'summary'?"
  }
]
}

The details array contains all validation issues found, with suggestions when available.

Error Codes

Authentication Errors (4xx)

Request Errors (4xx)

Resource Errors (4xx)

Server Errors (5xx)

Error Examples

Missing Authentication

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

Missing Project ID

{
"success": false,
"error": "Missing project identifier (website_id, schedule_id, or link_id)",
"code": "MISSING_PROJECT_ID"
}

Invalid Query Type

{
"success": false,
"error": "Unknown query type: summry",
"code": "INVALID_QUERY_TYPE"
}

Rate Limit Exceeded

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

Partial Success

When querying multiple parameters, individual queries can fail while others succeed:

{
"success": true,
"data": [
  {
    "parameter": "summary",
    "success": true,
    "data": [...]
  },
  {
    "parameter": "invalid_type",
    "success": false,
    "error": "Unknown query type: invalid_type",
    "data": []
  }
]
}

The top-level success: true indicates the request was processed. Check each parameter's success field for individual results.

Troubleshooting

"Authentication required"

• Ensure you're sending the API key in headers
• Check header format: x-api-key: dbdy_xxx or Authorization: Bearer dbdy_xxx
• Verify the API key hasn't been revoked

"Access denied"

• Check that your API key has access to this website
• Verify the API key has the required scope (read:data)
• For website-specific keys, ensure the website is in the allowed list

"Rate limit exceeded"

• Check the retryAfter field for when to retry
• Consider batching multiple queries into one request
• Upgrade your plan for higher limits

"Unknown query type"

• Check spelling of the query type
• Use GET /v1/query/types to see available types
• Some types require specific project IDs (e.g., link_* needs link_id)

"Hourly granularity only supports up to 7 days"

• Reduce your date range to 7 days or less
• Use "granularity": "daily" for longer ranges

Best Practices

1. Check success at both levels — Request success and parameter success

2. Handle rate limits gracefully — Implement exponential backoff

3. Log error codes — Use codes for programmatic handling, messages for debugging

4. Validate before sending — Check required fields client-side to avoid validation errors