Referencia de errores

Esta página documenta cada error que la API Scan de Cert-IX puede devolver, organizado por categoría.

Formato de respuesta

{
  "success": false,
  "error": "Descripción legible del error",
  "code": "CODIGO_LEGIBLE_POR_MAQUINA"
}

Códigos de estado HTTP

Estado	Categoría	Significado
400	Error del cliente	Solicitud inválida — JSON malformado, campos requeridos faltantes
401	Autenticación	Clave API faltante, inválida, expirada o revocada
403	Autorización	Clave válida pero alcance insuficiente, IP no permitida o tipo de análisis no permitido
404	No encontrado	El recurso no existe o no pertenece a su tenant
409	Conflicto	Conflicto de estado del recurso (ej.: cancelar un análisis ya completado)
429	Límite de tasa	Límite de tasa o cuota excedida
500	Error del servidor	Error interno — contacte soporte si persiste
503	No disponible	Servicio temporalmente no disponible — reintente con backoff

Errores de autenticación (401)

Código	Mensaje	Causa	Resolución
MISSING_API_KEY	La clave API es requerida	No se proporcionó encabezado X-API-Key	Agregue el encabezado X-API-Key a su solicitud
INVALID_API_KEY	Clave API inválida	El formato es incorrecto o la clave no existe	Verifique que la clave comience con cix_sk_
KEY_EXPIRED	La clave API ha expirado	La clave superó su fecha expiresAt	Cree una nueva clave o realice rotación
KEY_REVOKED	La clave API ha sido revocada	La clave fue explícitamente revocada	Cree una nueva clave
KEY_SUSPENDED	La clave API ha sido suspendida	La clave fue suspendida por un administrador	Contacte al administrador de su organización

Errores de autorización (403)

Código	Mensaje	Causa	Resolución
INSUFFICIENT_SCOPE	Alcance insuficiente: requiere {scope}	La clave no tiene el alcance requerido	Cree una nueva clave con el alcance requerido
SCAN_TYPE_NOT_ALLOWED	Tipo de análisis {type} no permitido	allowedScanTypes de la clave no incluye este motor	Actualice la clave o cree una que permita este tipo
IP_NOT_ALLOWED	IP de origen no está en la lista permitida	La IP de la solicitud no está en allowedIpAddresses	Agregue la IP de origen a la lista o elimine las restricciones
TENANT_SUSPENDED	La cuenta del tenant está suspendida	La cuenta de su organización ha sido suspendida	Contacte [email protected]

Errores de análisis (400 / 404 / 409)

Código	HTTP	Mensaje	Resolución
SCAN_NOT_FOUND	404	Análisis no encontrado	Verifique el ID del análisis y el parámetro scanType
INVALID_SCAN_TYPE	400	Tipo de análisis inválido: {type}	Use un motor válido: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel
INVALID_TARGET	400	Formato de objetivo inválido	Verifique que el objetivo coincida con el formato esperado
INVALID_PRIORITY	400	Prioridad inválida: {value}	Use: critical, high, normal o low
SCAN_ALREADY_COMPLETED	409	El análisis ya está completado	No se puede cancelar un análisis que alcanzó un estado terminal
SCAN_ALREADY_CANCELLED	409	El análisis ya está cancelado	El análisis ya fue cancelado
SCAN_ALREADY_FAILED	409	El análisis ya falló	No se puede cancelar un análisis fallido
RESULTS_NOT_READY	409	Los resultados aún no están disponibles	Espere a que el análisis alcance el estado completed

Errores de plantillas (400 / 404)

Código	HTTP	Mensaje	Resolución
TEMPLATE_NOT_FOUND	404	Plantilla de análisis no encontrada	Verifique el ID de la plantilla
TEMPLATE_NAME_REQUIRED	400	El nombre de la plantilla es requerido	Proporcione un campo name
DUPLICATE_TEMPLATE_NAME	400	El nombre de la plantilla ya existe	Use un nombre único

Errores de webhooks (400 / 404)

Código	HTTP	Mensaje	Resolución
WEBHOOK_NOT_FOUND	404	Webhook no encontrado	Verifique el ID del webhook
INVALID_WEBHOOK_URL	400	La URL del webhook debe usar HTTPS	Asegúrese de que su URL comience con https://
WEBHOOK_URL_UNREACHABLE	400	No se puede alcanzar la URL del webhook	Verifique que su endpoint sea accesible públicamente
INVALID_WEBHOOK_EVENT	400	Tipo de evento inválido: {event}	Use eventos válidos: scan.completed, scan.failed, scan.started, scan.cancelled
WEBHOOK_DISABLED	409	Webhook desactivado por fallos consecutivos	Reactive con PATCH y corrija su endpoint

Errores de límite de tasa y cuotas (429)

Código	Mensaje	Resolución
RATE_LIMIT_EXCEEDED	Límite de tasa excedido. Reintente en {N} segundos.	Implemente backoff exponencial; verifique el encabezado Retry-After
QUOTA_EXCEEDED	Cuota mensual de análisis excedida	Actualice su plan o espere al siguiente período de facturación

Errores de validación (400)

Código	Mensaje	Resolución
INVALID_JSON	El cuerpo de la solicitud no es JSON válido	Verifique su sintaxis JSON
MISSING_REQUIRED_FIELD	Campo requerido faltante: {field}	Incluya todos los campos requeridos
INVALID_FIELD_TYPE	El campo {field} debe ser de tipo {type}	Corrija el tipo de datos del campo
INVALID_PAGE	La página debe ser un entero positivo	Use page ≥ 1
INVALID_LIMIT	El límite debe estar entre 1 y 100	Use limit entre 1 y 100

Errores del servidor (500 / 503)

Código	Mensaje	Resolución
INTERNAL_ERROR	Se produjo un error interno del servidor	Reintente con backoff; contacte soporte si persiste
SERVICE_UNAVAILABLE	Servicio temporalmente no disponible	Reintente con backoff; verifique status.cert-ix.com
DATABASE_ERROR	La operación de base de datos falló	Reintente; contacte soporte si persiste
KAFKA_ERROR	La operación de cola de mensajes falló	Reintente; la cola puede estar temporalmente congestionada

Guía de resolución de problemas

« 401 — MISSING_API_KEY »

# ✅ Correcto
curl -H "X-API-Key: cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

# ❌ Incorrecto — clave en parámetros URL
curl "https://api.cert-ix.com/scan-api/api/v1/scans?apiKey=cix_sk_..."

« 404 — SCAN_NOT_FOUND »

Causas más comunes:

1. scanType incorrecto — Si creó un análisis zap, debe consultar con ?scanType=zap
2. ID de análisis incorrecto — Verifique el UUID
3. Tenant diferente — Las claves de organizaciones diferentes no pueden ver los análisis de las demás

« 429 — RATE_LIMIT_EXCEEDED »

Implemente backoff exponencial:

import time

def solicitud_con_backoff(func, max_reintentos=5):
    for intento in range(max_reintentos):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** intento))
        time.sleep(retry_after)
    raise Exception("Número máximo de reintentos superado")

---

Próximos pasos:

• Ejemplos de código →
• Primeros pasos →
• Autenticación →