Saltar al contenido principal
Version: Guardian v0.5.3

Códigos de error

Errores del SDK (SurtError)​

Cada plataforma reporta a su manera un verify() o collect() fallido.

iOS​

verify() y collect() fallan con un SurtError.

ErrorCuándo
.notInitializedverify() o collect() llamado antes de GuardianSDK.initialize()
.networkError(Error)Cualquier otro fallo: sin conexión, tiempo de espera agotado o un error HTTP de Surt. El error asociado describe la causa.

SurtError también declara .noCustomer, .invalidApiKey, .serverError y .attestationFailed. El SDK no los devuelve en esta versión.

Android​

ErrorCuándo
IllegalStateException (lanzada)GuardianSDK.getInstance() llamado antes de GuardianSDK.initialize()
java.io.IOException (en el Result)verify() recibió un error HTTP de Surt, o la solicitud no se completó. Para un error HTTP el mensaje empieza con HTTP <status>.
SurtError.NetworkError (en el Result)Un error inesperado dentro del SDK. underlying contiene la causa. collect() reporta todos los fallos de esta forma.

verifySuspend() y collectSuspend() devuelven un Result de Kotlin. Llama a .getOrThrow(), o maneja onSuccess y onFailure.

En ambas plataformas el SDK envía la solicitud de verify() hasta 3 veces antes de devolver un fallo.

React Native​

verify() y collect() rechazan con un error que tiene un code y un message. El message es una cadena JSON con su propio code y message.

Plataformaerror.codecode dentro de error.message
iOSverification_failed desde verify(), collect_failed desde collect()not_initialized o network_error
Androidverification_failed desde verify(), collect_failed desde collect(), sdk_error para un error inesperadoEl mismo valor que error.code
try {
const result = await verify(jwt);
} catch (e: any) {
let detail: { code?: string; message?: string } = {};
try {
detail = JSON.parse(e.message);
} catch {
// message was not JSON
}
console.warn(e.code, detail.code, detail.message);
}
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 que describe lo que el SDK observó durante la transacción. El código existente que no lo lee no se ve afectado. React Native lo devuelve a partir de v0.5.2. Algunos campos existen solo en algunas plataformas, como muestra la tabla.

// React Native (verify): diagnostics is on the result you already receive
const result = await GuardianSDK.verify(jwt);
console.log(result.diagnostics?.location); // e.g. "denied"
console.log(result.diagnostics?.warnings); // e.g. [{ code: "LOCATION_PERMISSION_DENIED", signal: "location" }]

// Web (collect): diagnostics sits alongside the payload
const { payload, diagnostics } = await collect({ collectLocation: true });
console.log(diagnostics.location);
// iOS (Swift): on the VerificationResult / CollectResult
let result = try await GuardianSDK.shared.verify(jwt: jwt)
print(result.diagnostics.location ?? "n/a")
// Android (Kotlin): on the VerificationResult / CollectResult
val result = GuardianSDK.getInstance().verifySuspend(jwt).getOrThrow()
Log.d("Guardian", result.diagnostics.location ?: "n/a")
CampoPlataformasValoresSignificado
locationTodascollected · denied · unavailable · timeout · not_requested · errorSi se capturó la ubicación del dispositivo, o por qué no (por ejemplo, el usuario denegó el permiso).
attestationiOS, Android, React Nativecollected · failed · unavailable · not_supported · not_requestedSi el dispositivo produjo una atestación (App Attest en iOS, Play Integrity en Android). collect() en Android también devuelve skipped cuando no correspondía atestar en esta transacción.
networkIntelTodascollected · unavailable · not_requestedSi la señal complementaria de inteligencia de red estuvo disponible para esta transacción.
timingsTodos (iOS desde v0.5.3)objeto de milisegundos por fase, más totalTiempo empleado en cada fase de la llamada.
warningsTodasarreglo de { code, signal, detail? }Notas no fatales que puedes registrar o mostrar a soporte. Siempre presente, posiblemente vacío.

En Android, location es collected cuando la app tiene el permiso de ubicación, incluso si el dispositivo no tenía ninguna ubicación que reportar.

Códigos de advertencia​

CódigosignalPlataformasSignificado
LOCATION_PERMISSION_DENIEDlocationTodasEl usuario denegó el permiso de ubicación.
LOCATION_UNAVAILABLElocationiOS, WebSe solicitó la ubicación pero no se obtuvo ninguna posición.
LOCATION_TIMEOUTlocationWebEl navegador no devolvió una posición a tiempo.
LOCATION_ERRORlocationWebLa API de Geolocalización del navegador falló.
ATTESTATION_FAILEDattestationiOS, AndroidSe intentó la atestación y falló.
ATTESTATION_UNAVAILABLEattestationiOS, AndroidLa atestación no está disponible en este dispositivo.
ATTESTATION_NOT_SUPPORTEDattestationAndroidEl dispositivo no admite la atestación.
NETWORK_INTEL_UNAVAILABLEnetwork_intelTodasNo se pudo recopilar la señal de inteligencia de red.
FINGERPRINT_DEGRADEDfingerprintWebNo se pudo calcular la huella digital del navegador.
{
"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, pide al usuario que habilite la ubicación cuando location sea denied.

Códigos de estado HTTP​

Aplican a los endpoints que llama tu backend: POST /geolocation/preflight y POST /geolocation/transactions/evaluate.

CódigoSignificado
200Éxito
400JSON malformado, falta un campo requerido o el valor de un campo es inválido
401La solicitud no tiene el encabezado Authorization
403La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización
404La ruta no coincide con ningún endpoint
409Solo evaluate: otra solicitud con el mismo event_id todavía se está evaluando. Reintenta después de una espera breve.
5xxError del servidor. Un 503 es temporal: reintenta la solicitud.

Un 401, y un 403 por una clave de API inválida o inactiva, tiene este cuerpo:

{
"error": "<reason>",
"message": "<description>",
"requestId": "<request id>"
}

Cualquier otro error usa el mismo sobre que una respuesta exitosa, con data igual a null:

{
"status_code": 409,
"message": "Conflict: This event_id is already being evaluated; retry shortly",
"data": null
}