Häufige Authentifizierungsfehler - Hilfecenter

Wenn du Probleme hast, dich mit der Cathopic-API zu authentifizieren, findest du hier die häufigsten Fehler und wie du sie behebst.

401 Unauthorized

Der häufigste Authentifizierungsfehler:

HTTP 401 Unauthorized
{
  "message": "Unauthorized"
}

Häufige Ursachen:

Fehlender x-api-key-Header
Ungültiger oder abgelaufener API-Schlüssel
Tippfehler im API-Schlüssel
Leerzeichen vor/nach dem Schlüssel
Schlüssel nicht aus der Umgebungsvariable geladen

So behebst du es:

Prüfe, ob der Header-Name exakt x-api-key ist (klein geschrieben)
Kopiere deinen API-Schlüssel erneut aus Einstellungen → API
Prüfe, ob Umgebungsvariablen geladen werden: console.log(process.env.CATHOPIC_API_KEY)
Leerzeichen entfernen: apiKey.trim()
Überprüfe, ob der Schlüssel aktiv ist (nicht gelöscht oder deaktiviert)

Falscher Header-Name

Die API benötigt x-api-key, nicht andere gängige Header-Namen:

// ❌ FALSCH
Authorization: Bearer sk_live_abc...
API-Key: sk_live_abc...
apikey: sk_live_abc...
// ✅ RICHTIG
x-api-key: sk_live_abc...

Fehler beim Unauthorized Token

HTTP 401 Unauthorized
{
  "error": "Unauthorized token"
}

Ursache: Dein API-Schlüssel wurde deaktiviert oder gelöscht.

So behebst du es:

Prüfe, ob der Schlüssel noch aktiv ist in Einstellungen → API
Aktiviere den Schlüssel erneut, falls er deaktiviert wurde
Erstelle einen neuen Schlüssel, falls der alte gelöscht wurde

Umgebungsvariable nicht geladen

Dein Code findet den API-Schlüssel nicht:

// Gibt undefined zurück
const apiKey = process.env.CATHOPIC_API_KEY;
console.log(apiKey); // undefined

So behebst du es:

Node.js:

// Stelle sicher, dass .env geladen wird
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
if (!apiKey) {
  throw new Error('CATHOPIC_API_KEY not set');
}

Python:

import os
from dotenv import load_dotenv
load_dotenv()
api_key = os.environ.get('CATHOPIC_API_KEY')
if not api_key:
    raise ValueError('CATHOPIC_API_KEY not set')

Fehler durch Offenlegung auf der Client-Seite

Versuchst du, den API-Schlüssel in Browser-JavaScript zu verwenden:

// ❌ Das wird fehlschlagen (Schlüssel funktionieren nicht im Browser)
fetch('https://api.cathopic.com/resources', {
  headers: { 'x-api-key': 'sk_live_abc...' }
});

So behebst du es: Erstelle einen serverseitigen Endpunkt, der Anfragen an die Cathopic-API weiterleitet (proxy). Siehe „Wie sichere ich meine Zugangsdaten?“ für Beispiele.

CORS-Fehler

Wenn du CORS-Fehler in der Browser-Konsole siehst:

Access to fetch has been blocked by CORS policy...

Ursache: Du versuchst, die API direkt aus clientseitigem JavaScript aufzurufen.

So behebst du es: Die Cathopic-API ist nur serverseitig verfügbar. Du musst Anfragen über dein eigenes Backend weiterleiten.

Authentifizierung testen

Schneller Test, um deine Einrichtung zu prüfen:

curl -v -X POST https://api.cathopic.com/resources \
  -H "x-api-key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}'
# Achte auf eine HTTP-200-Antwort
# Wenn 401, prüfe den Schlüssel sorgfältig

Debugging-Checkliste

Wenn die Authentifizierung weiterhin fehlschlägt:

☐ Der Header-Name ist x-api-key (Groß-/Kleinschreibung beachten)
☐ Der API-Schlüssel ist der vollständige Schlüssel (beginnt mit sk_live_ oder ähnlich)
☐ Kein Bearer-Präfix oder Anführungszeichen um den Schlüssel
☐ Die Umgebungsvariable ist gesetzt und wird geladen
☐ Die Anfrage wird serverseitig gesendet, nicht vom Browser
☐ Der Schlüssel ist aktiv in Einstellungen → API
☐ Die Zahlungsmethode ist hinzugefügt und gültig

Wenn die Probleme weiterhin bestehen, kontaktiere den Entwickler-Support mit:

Die Fehlermeldung
Die letzten 4 Ziffern deines API-Schlüssels
Programmiersprache und Framework
Beispielcode (ohne deinen vollständigen Schlüssel offenzulegen)