Manejo de Errores

Los endpoints de API de Gigantics retornan códigos de estado HTTP estándar y mensajes de error JSON para ayudar a los clientes a diagnosticar y manejar problemas.

Códigos de Estado HTTP

Formato de Respuesta de Error

Todas las respuestas de error siguen este formato JSON simple:

{
  "message": "Descripción del error"
}

El campo message contiene una descripción legible por humanos de qué salió mal.

Escenarios de Error Comunes

Clave API Faltante

Solicitud:

curl "https://yourserver/api/org/proj/model/1/dataset/42"

Respuesta:

{
  "message": "Not authorized"
}

Estado: 403 Forbidden

Resolución: Incluye la clave API vía parámetro de consulta (?api_key=...) o cabecera Authorization (Authorization: Bearer ...)

Clave API Inválida

Solicitud:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=invalid-key"

Respuesta:

{
  "message": "Unknown API key"
}

Estado: 403 Forbidden

Resolución: Verifica que la clave API sea correcta y esté asignada al endpoint

Clave API Inactiva

Respuesta:

{
  "message": "Disabled API key"
}

Estado: 403 Forbidden

Resolución: Activa la clave en la UI o usa una clave activa diferente

Endpoint Desconocido

Respuesta:

{
  "message": "Unknown API Endpoint"
}

Estado: 403 Forbidden

Resolución: Verifica que la URI del endpoint sea correcta y que se haya asignado un endpoint al recurso

Recurso No Encontrado

Solicitud:

curl "https://yourserver/api/org/proj/model/1/dataset/99999?api_key=valid-key"

Respuesta:

{
  "message": "Dataset not found"
}

Estado: 404 Not Found

Resolución: Verifica que el ID del conjunto de datos/pipeline exista y que la ruta URI sea correcta

Método HTTP Incorrecto

Solicitud:

curl -X POST "https://yourserver/api/org/proj/model/1/dataset/42?api_key=valid-key"

Respuesta:

{
  "message": "Endpoint or method not allowed"
}

Estado: 405 Method Not Allowed

Resolución: Usa GET para endpoints de conjunto de datos, POST para endpoints de pipeline

Parámetro de Formato Inválido

Solicitud:

curl "https://yourserver/api/org/proj/model/1/dataset/42?api_key=valid-key&format=invalid"

Respuesta:

{
  "message": "Unknown download format invalid, supported formats = json|sql|csv-zip|json-zip|oracle-loader"
}

Estado: 500 Internal Server Error

Resolución: Usa un formato válido: sql, json, csv-zip, json-zip, o oracle-loader

Error del Servidor

Respuesta:

{
  "message": "Mensaje de error detallado del servidor"
}

Estado: 500 Internal Server Error

Resolución: Verifica el mensaje de error para detalles. Reintenta con retroceso exponencial. Si persiste, contacta soporte.

Errores del Endpoint de Estado de Trabajo

El endpoint de estado de trabajo (/api/job/:jobId) es públicamente accesible (no requiere autenticación) y retorna:

ID de Trabajo Inválido

Respuesta:

{
  "id": "invalid-id",
  "message": "Invalid job id"
}

Estado: 404 Not Found

Trabajo No Encontrado

Respuesta:

{
  "job": "507f1f77bcf86cd799439011",
  "message": "Job is not available or has been deleted"
}

Estado: 404 Not Found

Conjunto de Datos No Disponible (para trabajos de dump)

Respuesta:

{
  "message": "Dataset is not available or has been deleted"
}

Estado: 404 Not Found

Mejores Prácticas de Manejo de Errores

Lógica de Reintento

1. SÍ reintenta:

   • 500 Internal Server Error - Problemas temporales del servidor
   • Timeouts de red

2. NO reintenta:

   • 403 Forbidden - Los problemas de autenticación no se resuelven reintentando
   • 404 Not Found - El recurso no existe
   • 405 Method Not Allowed - El método incorrecto no cambiará

3. Reintento condicional:

   • Verifica el estado del trabajo antes de reintentar endpoints de pipeline para evitar ejecuciones duplicadas

Retroceso Exponencial

Cuando reintentes, usa retroceso exponencial:

const delays = [1, 2, 4, 8, 16]; // segundos
for (let attempt = 0; attempt < delays.length; attempt++) {
  try {
    const response = await fetch(url);
    if (response.ok) break;
    if (response.status !== 500) break; // No reintentes errores no-5xx
  } catch (error) {
    if (attempt < delays.length - 1) {
      await sleep(delays[attempt] * 1000);
    }
  }
}

Registro

Registra errores con contexto:

• URL de solicitud
• Código de estado
• Mensaje de error
• Marca de tiempo
• Prefijo de clave API (no la clave completa)

Monitoreo

Monitorea para:

• Aumentos repentinos en errores 403 (posible compromiso de clave)
• Patrones de errores 404 (problemas de configuración)
• Errores 500 frecuentes (problemas del servidor)

Documentación Relacionada

• Asignación de Endpoints de API - Aprende cómo funcionan los endpoints
• Autenticación - Entiende la autenticación de claves API
• Múltiples Claves API por Endpoint - Aprende sobre gestión de claves