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.
| Error | Cuándo |
|---|---|
.notInitialized | verify() 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
| Error | Cuá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.
| Plataforma | error.code | code dentro de error.message |
|---|---|---|
| iOS | verification_failed desde verify(), collect_failed desde collect() | not_initialized o network_error |
| Android | verification_failed desde verify(), collect_failed desde collect(), sdk_error para un error inesperado | El 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);
}
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")
| Campo | Plataformas | Valores | Significado |
|---|---|---|---|
location | Todas | collected · denied · unavailable · timeout · not_requested · error | Si se capturó la ubicación del dispositivo, o por qué no (por ejemplo, el usuario denegó el permiso). |
attestation | iOS, Android, React Native | collected · failed · unavailable · not_supported · not_requested | Si 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. |
networkIntel | Todas | collected · unavailable · not_requested | Si la señal complementaria de inteligencia de red estuvo disponible para esta transacción. |
timings | Todos (iOS desde v0.5.3) | objeto de milisegundos por fase, más total | Tiempo empleado en cada fase de la llamada. |
warnings | Todas | arreglo 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ódigo | signal | Plataformas | Significado |
|---|---|---|---|
LOCATION_PERMISSION_DENIED | location | Todas | El usuario denegó el permiso de ubicación. |
LOCATION_UNAVAILABLE | location | iOS, Web | Se solicitó la ubicación pero no se obtuvo ninguna posición. |
LOCATION_TIMEOUT | location | Web | El navegador no devolvió una posición a tiempo. |
LOCATION_ERROR | location | Web | La API de Geolocalización del navegador falló. |
ATTESTATION_FAILED | attestation | iOS, Android | Se intentó la atestación y falló. |
ATTESTATION_UNAVAILABLE | attestation | iOS, Android | La atestación no está disponible en este dispositivo. |
ATTESTATION_NOT_SUPPORTED | attestation | Android | El dispositivo no admite la atestación. |
NETWORK_INTEL_UNAVAILABLE | network_intel | Todas | No se pudo recopilar la señal de inteligencia de red. |
FINGERPRINT_DEGRADED | fingerprint | Web | No se pudo calcular la huella digital del navegador. |
{
"diagnostics": {
"location": "denied",
"networkIntel": "collected",
"warnings": [{ "code": "LOCATION_PERMISSION_DENIED", "signal": "location" }]
}
}
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ódigo | Significado |
|---|---|
200 | Éxito |
400 | JSON malformado, falta un campo requerido o el valor de un campo es inválido |
401 | La solicitud no tiene el encabezado Authorization |
403 | La clave de API es inválida o está inactiva, o Guardian no está habilitado para tu organización |
404 | La ruta no coincide con ningún endpoint |
409 | Solo evaluate: otra solicitud con el mismo event_id todavía se está evaluando. Reintenta después de una espera breve. |
5xx | Error 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
}