API-Verbindungsfehler

Diagnostizieren und beheben Sie API-Verbindungsfehler, Authentifizierungsfehler und Integrationsprobleme.

Die Zenovay REST API ist nur für bezahlte Pläne verfügbar (Pro und höher). Keys im kostenlosen Plan werden mit einer 403 API_PAID_PLAN_REQUIRED Antwort abgelehnt — aktualisieren Sie auf einen kostenpflichtigen Plan, um API-Keys zu verwenden.

Authentifizierungsfehler

"Invalid API Key" (401)

Häufige Ursachen:

Falsches Schlüsselformat
- Der API-Schlüssel muss mit zv_ Präfix beginnen
- Schlüssel ohne dieses Präfix sind ungültig
- Überprüfen Sie, dass Sie den vollständigen Schlüssel vom Dashboard kopiert haben
Schlüssel widerrufen
- Gehen Sie zu Einstellungen → Konto → Sicherheit & Zugriff und öffnen Sie den Bereich Persönliche API-Schlüssel
- Erstellen Sie einen neuen Schlüssel, wenn der vorhandene widerrufen wurde
Schlüssel nur einmal gespeichert
- Der vollständige Schlüssel wird nur bei der Erstellung angezeigt — danach wird nur das Präfix gespeichert
- Wenn Sie ihn nicht kopiert haben, erstellen Sie einen neuen Schlüssel

Behebung:

// Falsch - ungültiges Format
const key = 'abc123_not_valid...';

// Richtig - Zenovay API-Schlüssel
const key = 'zv_xyz789abc...';

"API Key Not Found" (401)

Überprüfen Sie das Header-Format:

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

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

"API requires a paid plan" (403)

Die REST API ist eine bezahlte Funktion. Ein Schlüssel, der im (oder jetzt gebunden ist an) einem kostenlosen Plan erstellt wurde, gibt zurück:

{
  "error": "The Zenovay API requires a paid plan. Upgrade to Pro or higher to use API keys.",
  "code": "API_PAID_PLAN_REQUIRED"
}

Behebung: Aktualisieren Sie das Team auf Pro oder höher und erstellen Sie dann den Schlüssel unter Einstellungen → Konto → Sicherheit & Zugriff → Persönliche API-Schlüssel.

"Access denied to this website" (403)

Ein persönlicher API-Schlüssel hat zwei Bereiche, wenn Sie ihn erstellen:

Einstellung	Optionen
Berechtigungen	Vollzugriff oder nur Lesen / Schreiben / Admin
Team-Zugriff	Alle Teams, denen Sie angehören, oder nur ausgewählte Teams

Ein Schlüssel kann nur auf Websites in den Teams zugreifen, auf die er zugriff berechtigt ist (und nur solange Sie noch Mitglied dieser Teams sind). Falls eine Anfrage für eine bestimmte Website 403 zurückgibt, ist das Team, das sie besitzt, wahrscheinlich außerhalb des Team-Zugriffs des Schlüssels, oder Sie gehören nicht mehr zu diesem Team. Überprüfen Sie den Schlüssel unter Einstellungen → Konto → Sicherheit & Zugriff → Persönliche API-Schlüssel, oder erstellen Sie einen Schlüssel mit dem erforderlichen Zugriff.

Verbindungsfehler

"Connection Refused"

Überprüfen Sie den Endpunkt:

Richtig: https://api.zenovay.com/api/external/v1/
Falsch:  http://api.zenovay.com/api/external/v1/  (kein HTTPS)
Falsch:  https://zenovay.com/api/    (falsche Domain)

"Connection Timeout"

Ursachen:

Netzwerkprobleme
Firewall blockiert
DNS-Auflösungsfehler

Debug-Schritte:

Konnektivität testen:

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

DNS überprüfen:
```
nslookup api.zenovay.com
```
Firewall überprüfen:
- Ausgehend HTTPS (443) erlauben
- Domain api.zenovay.com erlauben

"SSL Certificate Error"

Ursachen:

Veraltete Root-Zertifikate
Proxy-Interferenz im Unternehmen
Zeituhr-Abweichung auf dem Server

Behebung:

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

# Systemzeit überprüfen
date

# Falls Sie Node.js verwenden, deaktivieren Sie die Verifizierung nicht:
// DON'T DO THIS IN PRODUCTION
// process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';

Rate-Limit-Fehler

"Rate Limit Exceeded" (429)

Response Headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-13T12:01:00.000Z
Retry-After: 42

Die API gibt auch Ihre monatliche Nutzung auf jeder Antwort zurück:

X-Usage-Monthly: 4231
X-Usage-Limit: 10000

Implementieren Sie 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;
    }
  }
}

REST API Rate Limits

Die REST API ist pro Schlüssel nach Plan-Tier begrenzt — sowohl eine Pro-Minute-Rate als auch ein monatliches Anfrage-Kontingent:

Plan	Pro Minute	Pro Monat
Pro	30 req/min	10.000
Scale	60 req/min	100.000
Enterprise	120 req/min	1.000.000

Das Überschreiten der Pro-Minute-Rate gibt 429 mit Retry-After zurück. Das Überschreiten des monatlichen Kontingents gibt 429 zurück und setzt sich am Anfang des nächsten Monats zurück (siehe die X-Usage-Monthly / X-Usage-Limit Header).

Tracking und öffentliche Endpunkt-Limits

Das Tracking-Ingest und andere öffentliche Endpunkte sind pro IP-Adresse (nicht pro Plan) begrenzt, unabhängig von REST API-Key-Limits:

Kontext	Limit
Tracking (Burst)	60 req/10 sec pro IP
Tracking (sustained)	5.000 req/hour pro IP
Öffentliche Endpunkte	30 req/min pro IP
Auth Endpunkte	30 req/min pro IP

Anfragefehler

"Bad Request" (400)

Häufige Probleme:

Ungültiges JSON:

// Falsch - Trailing Comma
{ "name": "Test", }

// Richtig
{ "name": "Test" }

Fehlende oder malformed Query-Parameter:

# Falsch - ungültiger Datumsbereich
GET /api/external/v1/analytics/{websiteId}?from=yesterday

# Richtig - ISO Daten
GET /api/external/v1/analytics/{websiteId}?from=2026-06-01&to=2026-06-13

Falsche Datentypen im Request Body:

// Falsch - String statt Nummer
{ "page": "1" }

// Richtig
{ "page": 1 }

"Not Found" (404)

Überprüfen Sie:

Endpunkt-URL ist korrekt
Ressourcen-ID existiert
Ressource gehört Ihrem Konto

# Endpunkt überprüfen (beachten Sie das /api/external/v1 Präfix und Plural "websites")
GET /api/external/v1/websites/{websiteId}  # Richtig
GET /api/external/v1/website/{websiteId}   # Falsch (Singular)

"Unprocessable Entity" (422)

Validierung fehlgeschlagen. Überprüfen Sie Response Body:

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

SDK-Fehler

JavaScript SDK

"Zenovay not defined":

<!-- Stellen Sie sicher, dass das Skript geladen wurde -->
<script src="https://api.zenovay.com/z.js"
        data-tracking-code="YOUR_TRACKING_CODE"></script>

<!-- Nach dem Laden überprüfen -->
<script>
  window.addEventListener('load', () => {
    if (typeof zenovay !== 'undefined') {
      console.log('Zenovay loaded');
    }
  });
</script>

Server-Side API Calls

Verbindungsprobleme mit dem Tracking-Endpunkt:

// Verwenden Sie fetch mit dem Tracking-Endpunkt - kein npm-Paket erforderlich.
// Der Ingest-Endpunkt validiert die Payload, also senden Sie das vollständige Event:
// session_id (min 8 Zeichen), eine absolute URL, user_agent und die
// Geräte-Felder (device_type, browser, os) sind alle erforderlich.
const response = await fetch('https://api.zenovay.com/e/YOUR_TRACKING_CODE', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
});

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

Timeout-Fehler:

// Verwenden Sie AbortController für Timeout-Kontrolle
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({
    event_type: 'pageview',
    url: 'https://example.com/home',
    session_id: 'srv-session-abcdef',
    user_agent: 'MyServer/1.0',
    device_type: 'desktop',
    browser: 'Server',
    os: 'Linux',
  }),
  signal: controller.signal,
});

clearTimeout(timeout);

Debug-Tipps

Debug-Modus aktivieren

In Server-Side Calls:

// Aktivieren Sie ausführliches Logging für 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());

Im Tracking-Skript:

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

API-Status überprüfen

Besuchen Sie status.zenovay.com
Überprüfen Sie den API-Endpunkt-Status
Überprüfen Sie die Incident-Historie

Key-Aktivität überprüfen

Im Dashboard:

Gehen Sie zu Einstellungen → Konto → Sicherheit & Zugriff und finden Sie Ihre Persönliche API-Schlüssel
Wählen Sie einen Schlüssel aus, um seine Detailansicht zu öffnen
Überprüfen Sie seine Aktivität — akzeptierte Event-Zählungen der letzten 24 Stunden, 7 Tage und insgesamt, sowie wann der Schlüssel zuletzt verwendet wurde

Mit cURL testen

# API-Schlüssel mit Usage-Endpunkt testen
curl -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/usage

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

# Mit ausführlicher Ausgabe
curl -v -H "X-API-Key: zv_..." \
     https://api.zenovay.com/api/external/v1/websites

Häufige Fehlercodes

Code	Bedeutung	Lösung
400	Bad request	Request Body überprüfen
401	Unauthorized	API-Schlüssel überprüfen
403	Forbidden	Berechtigungen überprüfen
404	Not found	Endpunkt/ID überprüfen
422	Validation failed	Feldwerte überprüfen
429	Rate limited	Backoff implementieren
500	Server error	Wiederholen, Support kontaktieren
502	Bad gateway	In 1 Minute wiederholen
503	Unavailable	Status-Seite überprüfen

Support kontaktieren

Wenn Sie API-Probleme melden, fügen Sie Folgendes ein:

Anfrage-Details:
- Endpunkt-URL
- HTTP-Methode
- Request Header (API-Schlüssel redaktieren)
- Request Body
Response-Details:
- Status-Code
- Response Body
- Response Header
Kontext:
- Zeitstempel
- Request ID (aus Headers)
- SDK-Version, falls relevant

E-Mail: [email protected]