Errores comunes de autenticación

Si tienes problemas autenticando con la API de Cathopic, estos son los errores más comunes y cómo solucionarlos.

401 Unauthorized

El error de autenticación más común:

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

Causas comunes:

• Falta el header x-api-key

• Clave API inválida o expirada

• Error tipográfico en la clave API

• Espacios en blanco antes/después de la clave

• Clave no cargada desde variable de entorno

Cómo solucionar:

1. Verifica que el nombre del header sea exactamente x-api-key (minúsculas)

2. Copia tu clave API de nuevo desde Ajustes → API

3. Comprueba que las variables de entorno están cargadas: console.log(process.env.CATHOPIC_API_KEY)

4. Recorta espacios en blanco: apiKey.trim()

5. Verifica que la clave está activa (no eliminada o desactivada)

Nombre de header incorrecto

La API requiere x-api-key, no otros nombres de header comunes:

// ❌ INCORRECTO
Authorization: Bearer sk_live_abc...
API-Key: sk_live_abc...
apikey: sk_live_abc...
// ✅ CORRECTO
x-api-key: sk_live_abc...

Error de token no autorizado

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

Causa: Tu clave API ha sido desactivada o eliminada.

Cómo solucionar:

• Comprueba si la clave sigue activa en Ajustes → API

• Reactiva la clave si fue desactivada

• Genera una nueva clave si la antigua fue eliminada

Variable de entorno no cargada

Tu código no puede encontrar la clave API:

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

Cómo solucionar:

Node.js:

// Asegúrate de que .env está cargado
require('dotenv').config();
const apiKey = process.env.CATHOPIC_API_KEY;
if (!apiKey) {
  throw new Error('CATHOPIC_API_KEY no está configurada');
}

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 no está configurada')

Error de exposición del lado del cliente

Intentando usar clave API en JavaScript del navegador:

// ❌ Esto fallará (las claves no funcionan en navegadores)
fetch('https://api.cathopic.com/resources', {
  headers: { 'x-api-key': 'sk_live_abc...' }
});

Cómo solucionar: Crea un endpoint del lado del servidor que haga proxy de peticiones a la API de Cathopic. Consulta "¿Cómo aseguro mis credenciales?" para ejemplos.

Errores CORS

Si ves errores CORS en la consola del navegador:

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

Causa: Estás intentando llamar a la API directamente desde JavaScript del lado del cliente.

Cómo solucionar: La API de Cathopic es solo del lado del servidor. Debes crear un proxy de peticiones a través de tu propio backend.

Probar autenticación

Prueba rápida para verificar tu configuración:

curl -v -X POST https://api.cathopic.com/resources \
  -H "x-api-key: TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{"query":"test","page":1,"page_size":1}'
# Busca respuesta HTTP 200
# Si es 401, verifica la clave cuidadosamente

Lista de verificación de depuración

Si la autenticación aún falla:

• ☐ El nombre del header es x-api-key (sensible a mayúsculas)

• ☐ La clave API es la clave completa (comienza con sk_live_ o similar)

• ☐ Sin prefijo Bearer o comillas alrededor de la clave

• ☐ La variable de entorno está configurada y cargada

• ☐ La petición se envía desde el lado del servidor, no del navegador

• ☐ La clave está activa en Ajustes → API

• ☐ El método de pago está añadido y es válido

Si los problemas persisten, contacta con soporte para desarrolladores con:

• El mensaje de error

• Últimos 4 dígitos de tu clave API

• Lenguaje de programación y framework

• Código de ejemplo (sin exponer tu clave completa)