Códigos de Error

Referencia completa de todos los códigos de error que puede devolver la API.

Estructura de error

Todas las respuestas de error siguen este formato:

{
  "success": false,
  "error": "Mensaje descriptivo del error",
  "code": "CODIGO_ERROR"
}

Algunos errores incluyen campos adicionales como details o retryAfter.

Errores de autenticación (401)

Código	Descripción	Solución
`MISSING_API_KEY`	Falta el header X-Api-Key	Incluye el header en el request
`MISSING_TIMESTAMP`	Falta el header X-Timestamp	Incluye el timestamp en milisegundos
`MISSING_SIGNATURE`	Falta el header X-Signature	Calcula e incluye la firma HMAC
`INVALID_API_KEY`	API Key no válida o no encontrada	Verifica que tu API Key sea correcta
`INVALID_TIMESTAMP`	Timestamp fuera de la ventana de 5 minutos	Sincroniza el reloj del sistema
`INVALID_SIGNATURE`	La firma HMAC no coincide	Revisa el cálculo de la firma
`ACCOUNT_PENDING`	La cuenta está pendiente de aprobación	Espera la aprobación del administrador
`ACCOUNT_SUSPENDED`	La cuenta ha sido suspendida	Contacta con soporte
`ACCOUNT_BANNED`	La cuenta ha sido baneada temporalmente	Espera hasta la fecha indicada en `bannedUntil`
`ACCOUNT_REJECTED`	La solicitud fue rechazada	Contacta con soporte
`ACCOUNT_NOT_APPROVED`	La cuenta no está aprobada	Espera la aprobación
`NO_CREDENTIALS`	Credenciales no configuradas	Contacta con soporte

Errores de validación (400)

Código	Descripción	Solución
`INVALID_JSON`	El body no es JSON válido	Verifica el formato JSON
`INVALID_BODY`	El body no cumple el schema	Revisa los campos requeridos
`INVALID_URL`	La URL no es válida o está prohibida	Usa una URL HTTP/HTTPS pública

Validación de URL

La API rechaza URLs que:

No usen protocolo HTTP o HTTPS
Apunten a localhost (127.0.0.1, ::1)
Apunten a IPs privadas (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
Usen hostnames internos (.local, .internal)
Apunten a servicios de metadata cloud

Errores de límites (429)

Código	Descripción	Solución
`RATE_LIMIT_EXCEEDED`	Límite por minuto excedido	Espera 1 minuto
`HOURLY_LIMIT_REACHED`	Límite por hora excedido	Espera hasta la siguiente hora
`DAILY_LIMIT_REACHED`	Límite diario excedido	Espera hasta mañana
`TOTAL_LIMIT_REACHED`	Límite total de cuenta excedido	Solicita aumento de límites

Campo retryAfter

Los errores de límites incluyen un campo retryAfter con los segundos recomendados de espera:

{
  "success": false,
  "error": "Rate limit exceeded. Please slow down.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 60
}

Errores de servidor (500/503)

Código	Descripción	Solución
`SERVICE_UNAVAILABLE`	Servicio temporalmente no disponible	Reintenta en unos minutos
`ANALYSIS_ERROR`	Error durante el análisis	Reintenta; si persiste, contacta soporte

Manejo recomendado

Errores no reintentables

Estos errores indican problemas de configuración que no se resolverán con reintentos:

MISSING_* - Falta información requerida
INVALID_API_KEY - Credenciales incorrectas
INVALID_SIGNATURE - Error en el cálculo de firma
ACCOUNT_* - Problemas de estado de cuenta
INVALID_BODY - Request malformado
INVALID_URL - URL no permitida

Errores reintentables

Estos errores pueden resolverse con reintentos:

RATE_LIMIT_EXCEEDED, HOURLY_LIMIT_REACHED, DAILY_LIMIT_REACHED, TOTAL_LIMIT_REACHED - Espera el tiempo indicado en retryAfter
SERVICE_UNAVAILABLE - Espera unos minutos
ANALYSIS_ERROR - Reintenta con backoff exponencial

Ejemplo de manejo

function shouldRetry(code) {
  const noRetry = [
    'MISSING_API_KEY',
    'MISSING_TIMESTAMP',
    'MISSING_SIGNATURE',
    'INVALID_API_KEY',
    'INVALID_SIGNATURE',
    'ACCOUNT_PENDING',
    'ACCOUNT_SUSPENDED',
    'ACCOUNT_BANNED',
    'ACCOUNT_REJECTED',
    'ACCOUNT_NOT_APPROVED',
    'NO_CREDENTIALS',
    'INVALID_JSON',
    'INVALID_BODY',
    'INVALID_URL',
  ];
  return !noRetry.includes(code);
}

function getRetryDelay(code, retryAfter, attempt) {
  // Si hay retryAfter, usarlo
  if (retryAfter) {
    return retryAfter * 1000;
  }

  // Backoff exponencial para otros errores
  return Math.min(Math.pow(2, attempt) * 1000, 60000);
}

Headers de Rate Limit

Todas las respuestas incluyen headers informativos sobre tus límites actuales:

X-RateLimit-Limit-Minute: 3
X-RateLimit-Limit-Hour: 20
X-RateLimit-Limit-Day: 100
X-RateLimit-Limit-Total: 1000
X-RateLimit-Remaining-Minute: 2
X-RateLimit-Remaining-Hour: 19
X-RateLimit-Remaining-Day: 99
X-RateLimit-Remaining-Total: 999

Usa estos headers para implementar rate limiting proactivo en tu cliente y evitar errores 429.

Códigos de Error

On this page