Zenovay Help Center

Diagnose and resolve API connection errors, authentication failures, and integration issues.

Authentication Errors

"Invalid API Key" (401)

Common causes:

Wrong key format
- API key must start with zv_ prefix
- Keys without this prefix are invalid
- Check you copied the full key from dashboard
Key not activated
- New keys need 1-2 minutes
- Regenerate if still failing
Key revoked
- Check API Keys in dashboard
- Generate new key if revoked

Fix:

// Wrong - invalid format
const key = 'abc123_not_valid...';

// Correct - Zenovay API key
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

Check header format:

# Wrong
curl -H "Api-Key: zv_..."

# Correct (External API)
curl -H "X-API-Key: zv_..."

"Insufficient Permissions" (403)

Your API key lacks required scope:

Operation	Required Scope
Read analytics	`analytics:read`
Create goals	`goals:write`
Manage websites	`websites:admin`

Fix: Generate new key with correct scopes.

Connection Errors

"Connection Refused"

Check endpoint:

Correct: https://api.zenovay.com/api/external/v1/
Wrong:   http://api.zenovay.com/api/external/v1/  (no HTTPS)
Wrong:   https://zenovay.com/api/    (wrong domain)

"Connection Timeout"

Causes:

Network issues
Firewall blocking
DNS resolution failure

Debug steps:

Test connectivity:

curl -v https://api.zenovay.com/api/external/v1/usage

Check DNS:
```
nslookup api.zenovay.com
```
Check firewall:
- Allow outbound HTTPS (443)
- Allow api.zenovay.com domain

"SSL Certificate Error"

Causes:

Outdated root certificates
Corporate proxy interference
Clock skew on server

Fix:

# Update certificates (Ubuntu)
sudo apt update && sudo apt install ca-certificates

# Check system time
date

# If using Node.js, don't disable verification:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Rate Limit Errors

"Rate Limit Exceeded" (429)

Response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Retry-After: 60

Implement backoff:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429) {
        const retryAfter = error.headers.get('Retry-After') || 60;
        await sleep(retryAfter * 1000);
        continue;
      }
      throw error;
    }
  }
}

Rate Limits

Rate limits are per-IP, not per-plan:

Context	Limit
Default API	100 req/min per IP
Auth endpoints	30 req/min per IP
Tracking (burst)	60 req/10sec per IP
Tracking (sustained)	5,000 req/hour per IP
Public endpoints	30 req/min per IP

Request Errors

"Bad Request" (400)

Common issues:

Invalid JSON:

// Wrong - trailing comma
{ "name": "Test", }

// Correct
{ "name": "Test" }

Missing required fields:

// Missing website_id
POST /v1/goals
{ "name": "Signup" }

// Correct
POST /v1/goals
{ "name": "Signup", "website_id": "web_123" }

Wrong data types:

// Wrong - string instead of number
{ "page": "1" }

// Correct
{ "page": 1 }

"Not Found" (404)

Check:

Endpoint URL is correct
Resource ID exists
Resource belongs to your account

# Verify endpoint
GET /v1/websites/web_123  # Correct
GET /v1/website/web_123   # Wrong (singular)

"Unprocessable Entity" (422)

Validation failed. Check response body:

{
  "error": "validation_error",
  "details": {
    "url": "Invalid URL format",
    "name": "Name too long (max 100 characters)"
  }
}

SDK Errors

JavaScript SDK

"Zenovay not defined":

<!-- Ensure script loaded -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- Check after load -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

Server-Side API Calls

Connection issues with the tracking endpoint:

// Use fetch with the tracking endpoint - no npm package needed
const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    type: 'page_view',
    url: '/home',
  }),
});

if (!response.ok) {
  console.error('Zenovay tracking error:', response.status);
}

Timeout errors:

// Use AbortController for timeout control
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);

const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ type: 'page_view', url: '/home' }),
  signal: controller.signal,
});

clearTimeout(timeout);

Debugging Tips

Enable Debug Mode

In server-side calls:

// Enable verbose logging for External API calls
const response = await fetch('https://api.zenovay.com/api/external/v1/websites', {
  headers: { 'X-API-Key': 'zv_...' },
});
console.log('Status:', response.status);
console.log('Response:', await response.json());

In tracking script:

<script data-tracking-code="YOUR_TRACKING_CODE"
        data-debug="true"
        src="..."></script>

Check API Status

Visit status.zenovay.com
Check API endpoint status
Review incident history

View Request Logs

In dashboard:

Go to Settings → API
Click Request Logs
Filter by status, endpoint, time

Test with cURL

# Test API key with usage endpoint
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

# List websites
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

# With verbose output
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

Common Error Codes

Code	Meaning	Solution
400	Bad request	Check request body
401	Unauthorized	Check API key
403	Forbidden	Check permissions
404	Not found	Check endpoint/ID
422	Validation failed	Check field values
429	Rate limited	Implement backoff
500	Server error	Retry, contact support
502	Bad gateway	Retry in 1 minute
503	Unavailable	Check status page

Contacting Support

When reporting API issues, include:

Request details:
- Endpoint URL
- HTTP method
- Request headers (redact API key)
- Request body
Response details:
- Status code
- Response body
- Response headers
Context:
- Timestamp
- Request ID (from headers)
- SDK version if applicable

Email: support@zenovay.com

API Connection Errors