Errori comuni di autenticazione

Se hai difficoltà ad autenticarti con l’API di Cathopic, ecco i problemi più comuni e come risolverli.

401 Unauthorized

L’errore di autenticazione più comune:

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

Cause comuni:

• Header x-api-key mancante

• Chiave API non valida o scaduta

• Refuso nella chiave API

• Spazi bianchi prima/dopo la chiave

• Chiave non caricata dalla variabile d’ambiente

Come risolvere:

1. Verifica che il nome dell’header sia esattamente x-api-key (minuscolo)

2. Copia di nuovo la tua chiave API da Impostazioni → API

3. Controlla che le variabili d’ambiente siano caricate: console.log(process.env.CATHOPIC_API_KEY)

4. Rimuovi gli spazi bianchi: apiKey.trim()

5. Verifica che la chiave sia attiva (non eliminata o disattivata)

Nome dell’header errato

L’API richiede x-api-key, non altri nomi di header comuni:

// ❌ SBAGLIATO
Authorization: Bearer sk_live_abc...
API-Key: sk_live_abc...
apikey: sk_live_abc...
// ✅ CORRETTO
x-api-key: sk_live_abc...

Errore di token non autorizzato

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

Causa: La tua chiave API è stata disattivata o eliminata.

Come risolvere:

• Controlla se la chiave è ancora attiva in Impostazioni → API

• Riattiva la chiave se era stata disattivata

• Genera una nuova chiave se quella vecchia è stata eliminata

Variabile d’ambiente non caricata

Il tuo codice non riesce a trovare la chiave API:

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

Come risolvere:

Node.js:

// Assicurati che .env sia caricato
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
if (!apiKey) {
  throw new Error('CATHOPIC_API_KEY non impostata');
}

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 non impostata')

Errore di esposizione lato client

Stai cercando di usare la chiave API nel browser tramite JavaScript:

// ❌ Questo fallirà (le chiavi non funzionano nei browser)
fetch('https://api.cathopic.com/resources', {
  headers: { 'x-api-key': 'sk_live_abc...' }
});

Come risolvere: Crea un endpoint lato server che faccia da proxy alle richieste verso l’API di Cathopic. Vedi "Come posso proteggere le mie credenziali?" per esempi.

Errori CORS

Se vedi errori CORS nella console del browser:

Accesso a fetch è stato bloccato dalla policy CORS...

Causa: Stai cercando di chiamare l’API direttamente da JavaScript lato client.

Come risolvere: L’API di Cathopic è solo lato server. Devi fare da proxy alle richieste tramite il tuo backend.

Test dell’autenticazione

Test rapido per verificare la configurazione:

curl -v -X POST https://api.cathopic.com/resources \
  -H "x-api-key: LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}'
# Cerca una risposta HTTP 200
# Se 401, controlla attentamente la chiave

Checklist di debug

Se l’autenticazione continua a fallire:

• ☐ Il nome dell’header è x-api-key (sensibile alle maiuscole/minuscole)

• ☐ La chiave API è l’intera chiave (inizia con sk_live_ o simile)

• ☐ Nessun prefisso Bearer o virgolette attorno alla chiave

• ☐ La variabile d’ambiente è impostata e caricata

• ☐ La richiesta viene inviata dal server, non dal browser

• ☐ La chiave è attiva in Impostazioni → API

• ☐ Il metodo di pagamento è aggiunto e valido

Se i problemi persistono, contatta l’assistenza per sviluppatori con:

• Il messaggio di errore

• Le ultime 4 cifre della tua chiave API

• Linguaggio di programmazione e framework

• Esempio di codice (senza esporre la tua chiave completa)