Códigos de error

Errores del SDK (SurtError)

Error	Cuándo
notInitialized	verify() llamado antes de initialize()
invalidJwt	JWT faltante, malformado o rechazado por el backend. Genera un JWT fresco por cada verify().
networkError	Tiempo de espera agotado o sin conexión
serverError	5xx del backend
attestationFailed	Falló una verificación de integridad del dispositivo, normalmente un JWT reutilizado. Genera un JWT fresco para cada verify().

Las plataformas nativas exponen estos como .notInitialized / .invalidJwt / etc. El puente de React Native expone códigos de cadena: not_initialized, invalid_jwt, attestation_failed, network_error.

Errores del SDK web

El SDK web (@surtai/guardian-web) usa un GuardianError independiente con los códigos CRYPTO_UNAVAILABLE, ENCRYPTION_FAILED e INVALID_OPTIONS. Consulta Paquete NPM.

Diagnósticos del resultado

Cada resultado de verify() y collect() incluye un objeto diagnostics. Lo lees directamente del resultado que ya recibes: es aditivo, así que el código existente no se ve afectado. La forma es idéntica en Web, iOS, Android y React Native.

// React Native (verify) — diagnostics está en el resultado que ya recibes
const result = await GuardianSDK.verify(jwt);
console.log(result.diagnostics?.location);     // p. ej. "denied"
console.log(result.diagnostics?.warnings);     // p. ej. [{ code: "LOCATION_PERMISSION_DENIED", signal: "location" }]

// Web (collect) — diagnostics va junto al payload
const { payload, diagnostics } = await collect({ collectLocation: true });
console.log(diagnostics.location);

// iOS (Swift) — en el VerificationResult / CollectResult
let result = try await GuardianSDK.shared.verify(jwt: jwt)
print(result.diagnostics.location ?? "n/a")

// Android (Kotlin) — en el VerificationResult / CollectResult
val result = GuardianSDK.getInstance().verifySuspend(jwt).getOrThrow()
Log.d("Guardian", result.diagnostics.location ?: "n/a")

Campo	Valores	Significado
location	collected · denied · unavailable · timeout · not_requested	Si se capturó la ubicación del dispositivo, o por qué no (p. ej. el usuario denegó el permiso).
networkIntel	collected · unavailable · not_requested	Si la señal complementaria de inteligencia de red estuvo disponible para esta transacción.
warnings	array de { code, signal, detail? }	Notas estructuradas no fatales que puedes registrar o mostrar a soporte (p. ej. LOCATION_PERMISSION_DENIED).

{
  "diagnostics": {
    "location": "denied",
    "networkIntel": "collected",
    "warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
  }
}

tip

Usa diagnostics para explicar los resultados a tus usuarios o a tu equipo de soporte; por ejemplo, pedir al usuario que active la ubicación cuando location es denied.

Códigos de estado HTTP

Código	Significado
200	Éxito
400	JSON malformado o campo requerido faltante
401	JWT Bearer inválido o faltante
403	Clave válida pero permiso faltante
5xx	Error del servidor