Errores

Esta guía describe los códigos de error que pueden retornar las APIs de JAAK, junto con recomendaciones para resolverlos.

Formato de respuesta de error

Todas las respuestas de error siguen el mismo formato JSON:

{
  "error": {
    "code": "invalid_token",
    "message": "El token ha expirado",
    "status": 401,
    "details": {
      "expiredAt": "2024-01-15T10:30:00Z"
    }
  }
}

---

Códigos de estado HTTP

400 Bad Request

La solicitud contiene errores de sintaxis o parámetros inválidos.

{
  "error": {
    "code": "invalid_request",
    "message": "El campo 'email' es requerido",
    "status": 400,
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

Solución:

• Verifica que todos los campos requeridos estén presentes
• Comprueba que los tipos de datos sean correctos (string, number, etc.)
• Revisa que los valores estén en formato válido (email, URL, fecha ISO 8601)

401 Unauthorized

Las credenciales son inválidas o no fueron proporcionadas.

{
  "error": {
    "code": "invalid_credentials",
    "message": "API Key o API Secret inválidos",
    "status": 401
  }
}

Solución:

• Verifica que estés enviando los headers de autenticación correctos
• Comprueba que las credenciales sean las correctas para el ambiente (sandbox vs producción)
• Revisa que los tokens no hayan expirado

403 Forbidden

No tienes permisos para acceder al recurso solicitado.

{
  "error": {
    "code": "forbidden",
    "message": "No tienes permisos para acceder a este recurso",
    "status": 403
  }
}

Solución:

• Verifica que tu plan incluya acceso a esta funcionalidad
• Comprueba que el usuario tenga los permisos necesarios
• Contacta a soporte si crees que deberías tener acceso

404 Not Found

El recurso solicitado no existe.

{
  "error": {
    "code": "not_found",
    "message": "Sesión no encontrada",
    "status": 404,
    "details": {
      "resourceType": "session",
      "resourceId": "ses_abc123xyz"
    }
  }
}

Solución:

• Verifica que el ID del recurso sea correcto
• Comprueba que el recurso exista en el ambiente correcto
• El recurso pudo haber sido eliminado o expirado

422 Unprocessable Entity

La solicitud es válida pero no puede ser procesada debido a reglas de negocio.

{
  "error": {
    "code": "session_already_completed",
    "message": "La sesión ya fue completada y no puede modificarse",
    "status": 422,
    "details": {
      "sessionId": "ses_abc123xyz",
      "status": "completed"
    }
  }
}

Solución:

• Revisa el estado actual del recurso antes de intentar modificarlo
• Consulta la documentación para entender las transiciones de estado válidas

429 Too Many Requests

Has excedido el límite de solicitudes permitidas.

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de solicitudes. Intenta de nuevo en 60 segundos",
    "status": 429,
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "window": "1m"
    }
  }
}

Solución:

• Implementa backoff exponencial en tu código
• Respeta el header Retry-After en la respuesta
• Considera cachear respuestas cuando sea posible
• Contacta a soporte si necesitas un límite mayor

500 Internal Server Error

Error interno del servidor. No es tu culpa.

{
  "error": {
    "code": "internal_error",
    "message": "Ha ocurrido un error interno. Por favor intenta de nuevo",
    "status": 500,
    "details": {
      "requestId": "req_xyz789"
    }
  }
}

Solución:

• Reintenta la solicitud después de unos segundos
• Si el error persiste, contacta a soporte con el requestId

---

Códigos de error específicos

Errores de autenticación

Errores de verificación (KYC)

Errores de firma (Signa)

Errores de validación

---

Rate Limiting

Las APIs de JAAK implementan límites de solicitudes para garantizar la estabilidad del servicio.

Límites por defecto

Headers de rate limit

Cada respuesta incluye headers con información del límite:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315200

Manejo de rate limits

Implementa backoff exponencial cuando recibas un error 429:

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 && attempt < maxRetries - 1) {
        const retryAfter = error.details?.retryAfter || Math.pow(2, attempt);
        console.log(`Rate limited. Esperando ${retryAfter} segundos...`);
        await sleep(retryAfter * 1000);
      } else {
        throw error;
      }
    }
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

---

Errores de verificación de identidad

Estos errores ocurren durante el proceso de verificación y se reportan en el resultado de la sesión.

Errores de documento

Errores de liveness

Errores de face match

Errores de validación INE

---

Manejo de errores en tu código

Ejemplo completo

class JAAKError extends Error {
  constructor(response) {
    super(response.error.message);
    this.code = response.error.code;
    this.status = response.error.status;
    this.details = response.error.details;
  }
}

async function callJAAKAPI(endpoint, options) {
  const response = await fetch(`https://api.jaak.ai${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': API_KEY,
      'X-API-Secret': API_SECRET,
      ...options.headers
    }
  });

  const data = await response.json();

  if (!response.ok) {
    throw new JAAKError(data);
  }

  return data;
}

// Uso con manejo de errores
async function createSession(verificationType) {
  try {
    const session = await callJAAKAPI('/api/v1/sessions', {
      method: 'POST',
      body: JSON.stringify({ verificationType })
    });
    return session;
  } catch (error) {
    if (error instanceof JAAKError) {
      switch (error.code) {
        case 'rate_limit_exceeded':
          console.log('Esperando antes de reintentar...');
          await sleep(error.details.retryAfter * 1000);
          return createSession(verificationType);

        case 'invalid_credentials':
          console.error('Credenciales inválidas. Verifica tu API Key y Secret.');
          throw error;

        case 'forbidden':
          console.error('No tienes acceso a este tipo de verificación.');
          throw error;

        default:
          console.error(`Error de JAAK: ${error.message} (${error.code})`);
          throw error;
      }
    }
    throw error;
  }
}

---

Contactar a soporte

Si encuentras un error que no puedes resolver:

1. Incluye el Request-Id del header de respuesta
2. Describe los pasos para reproducir el error
3. Incluye el código de error y mensaje completo
4. Indica el ambiente (sandbox o producción)

Email: soporte@jaak.ai

---

Siguientes pasos

• Webhooks - Configura notificaciones en tiempo real
• Sandbox - Prueba tu integración sin afectar producción