Najczęstsze błędy uwierzytelniania

Jeśli masz problem z uwierzytelnianiem się za pomocą API Cathopic, poniżej znajdziesz najczęstsze błędy oraz sposoby ich naprawy.

401 Unauthorized

Najczęstszy błąd uwierzytelniania:

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

Najczęstsze przyczyny:

• Brak nagłówka x-api-key

• Nieprawidłowy lub wygasły klucz API

• Literówka w kluczu API

• Spacje przed/po kluczu

• Klucz nie został wczytany z zmiennej środowiskowej

Jak to naprawić:

1. Sprawdź, czy nazwa nagłówka jest dokładnie x-api-key (małe litery)

2. Ponownie skopiuj swój klucz API z Ustawienia → API

3. Sprawdź, czy zmienne środowiskowe są wczytane: console.log(process.env.CATHOPIC_API_KEY)

4. Usuń białe znaki: apiKey.trim()

5. Upewnij się, że klucz jest aktywny (nie usunięty ani nie zdezaktywowany)

Błędna nazwa nagłówka

API wymaga x-api-key, a nie innych popularnych nazw nagłówków:

// ❌ ŹLE
Authorization: Bearer sk_live_abc...
API-Key: sk_live_abc...
apikey: sk_live_abc...
// ✅ POPRAWNIE
x-api-key: sk_live_abc...

Błąd nieautoryzowanego tokenu

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

Przyczyna: Twój klucz API został zdezaktywowany lub usunięty.

Jak to naprawić:

• Sprawdź, czy klucz nadal jest aktywny w Ustawienia → API

• Aktywuj ponownie klucz, jeśli został zdezaktywowany

• Wygeneruj nowy klucz, jeśli stary został usunięty

Nie wczytano zmiennej środowiskowej

Twój kod nie znajduje klucza API:

// Zwraca undefined
const apiKey = process.env.CATHOPIC_API_KEY;
console.log(apiKey); // undefined

Jak to naprawić:

Node.js:

// Upewnij się, że .env jest wczytany
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')

Błąd ujawnienia po stronie klienta

Próba użycia klucza API w przeglądarce (JavaScript):

// ❌ To się nie uda (klucze nie działają w przeglądarkach)
fetch('https://api.cathopic.com/resources', {
  headers: { 'x-api-key': 'sk_live_abc...' }
});

Jak to naprawić: Utwórz punkt końcowy po stronie serwera, który będzie pośredniczył w żądaniach do API Cathopic. Zobacz „Jak zabezpieczyć moje dane uwierzytelniające?” dla przykładów.

Błędy CORS

Jeśli w konsoli przeglądarki widzisz błędy CORS:

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

Przyczyna: Próbujesz wywołać API bezpośrednio z kodu JavaScript po stronie klienta.

Jak to naprawić: API Cathopic działa tylko po stronie serwera. Musisz przekazywać żądania przez własny backend.

Testowanie uwierzytelniania

Szybki test, aby zweryfikować konfigurację:

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}'
# Sprawdź odpowiedź HTTP 200
# Jeśli 401, uważnie sprawdź klucz

Lista kontrolna debugowania

Jeśli uwierzytelnianie nadal nie działa:

• ☐ Nazwa nagłówka to x-api-key (rozróżniana jest wielkość liter)

• ☐ Klucz API to pełny klucz (zaczyna się od sk_live_ lub podobnego)

• ☐ Brak prefiksu Bearer lub cudzysłowów wokół klucza

• ☐ Zmienna środowiskowa jest ustawiona i wczytana

• ☐ Żądanie jest wysyłane z serwera, a nie z przeglądarki

• ☐ Klucz jest aktywny w Ustawienia → API

• ☐ Dodano metodę płatności i jest ona ważna

Jeśli problemy będą się utrzymywać, skontaktuj się z wsparciem dla deweloperów podając:

• Komunikat o błędzie

• Ostatnie 4 cyfry twojego klucza API

• Język programowania i framework

• Przykładowy kod (bez ujawniania pełnego klucza)