Códigos de error comunes de la API

Entender las respuestas de error te ayuda a depurar problemas rápidamente. Estos son los errores más comunes que encontrarás.

400 Bad Request

{
  "error": "media_id is required"
}

Causas:

• Falta parámetro requerido

• Formato de parámetro inválido

• JSON mal formado

Solución: Verifica que tu cuerpo de petición coincida con la especificación de la API en api.cathopic.com/docs.

401 Unauthorized

{
  "message": "Unauthorized"
}
o
{
  "error": "Unauthorized token"
}

Causas:

• Clave API faltante o inválida

• Clave API desactivada

• Nombre de header incorrecto

Solución: Verifica que tu header x-api-key sea correcto y la clave esté activa en Ajustes → API.

404 Not Found

{
  "error": "No file found for media_id 1234"
}
o
{
  "error": "Media item not found"
}

Causas:

• El recurso no existe

• El recurso ha sido eliminado

• media_id incorrecto

Solución: Verifica que el media_id existe buscando primero con /resources.

429 Too Many Requests

{
  "error": "Limit exceed."
}

Causas:

• Demasiadas peticiones en poco tiempo

• Límite de tasa excedido

Solución: Implementa retroceso exponencial. Espera y reintenta con retrasos crecientes (1s, 2s, 4s, etc.).

500 Internal Server Error

{
  "error": "Internal server error"
}

Causas:

• Problema temporal del servidor

• Condición inesperada

Solución: Espera un momento y reintenta. Si persiste, contacta con soporte.

Ejemplo de manejo de errores

async function searchWithErrorHandling(query) {
  try {
    const response = await fetch('https://api.cathopic.com/resources', {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, page: 1, page_size: 20 })
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 400:
          console.error('Petición incorrecta:', error);
          break;
        case 401:
          console.error('No autorizado. Verifica tu clave API.');
          break;
        case 404:
          console.error('Recurso no encontrado:', error);
          break;
        case 429:
          console.error('Límite de tasa. Implementando retroceso...');
          await sleep(5000);
          return searchWithErrorHandling(query); // Reintentar
        case 500:
          console.error('Error de servidor. Reintentando en 10s...');
          await sleep(10000);
          return searchWithErrorHandling(query);
        default:
          console.error('Error desconocido:', error);
      }
      
      throw new Error(`Error de API: ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Petición fallida:', error);
    throw error;
  }
}

Para errores persistentes, consulta la documentación completa de la API o contacta con soporte.