Timeout en una API de verificación de identidad: recuperar sin asumir aprobación

El problema y la decisión que enfrenta

Un vendedor se registra, su servicio abre una sesión de identidad alojada y el proveedor es lento, inaccesible o no responde. Su código aún debe decidir qué ve el usuario y qué permite su aplicación. La decisión no es "aprobar o fallar", sino qué estado registrar y quién actúa después. La guía de fallos de proveedor de GridZen lo plantea así: un proveedor no disponible es un fallo operativo, no una señal de bajo riesgo. El adaptador actual de Twilio devuelve un 503 a través de la API cuando su proveedor no está disponible, y la alfa no convierte silenciosamente ese fallo en permitir. Una cola de revisión o un respaldo autorizado debe implementarlo su flujo llamante. Mantenga separados tres resultados: una discrepancia es una afirmación devuelta, la evidencia insuficiente significa que su política carece de una señal requerida, y un fallo técnico significa que la comprobación no pudo completarse. Registre el estado HTTP por separado del resultado de decisión; un 503 nunca debe registrarse como rechazo ni como permiso.

Lo que el fixture verificado implementa realmente

El ejemplo descargable es un fixture sintético sin dependencias, no un adaptador de proveedor real. Su parte de identidad persiste sesiones en SQLite. Llamar a create guarda una sesión con estado pending y un plazo igual a now más timeout; con los valores por defecto (now 0, timeout 60) el plazo es 60. El hosted_link devuelto apunta a un dominio de ejemplo inválido, link_executable es false y next es send_real_provider_link_only_after_authorization. El método event acepta solo callbacks sintéticos: mode debe ser synthetic_fixture y source debe ser fixture_callback; de lo contrario lanza PRODUCTION_SIGNATURE_VERIFIER_NOT_IMPLEMENTED. Los identificadores de evento deben empezar por fixture-. No existe verificación real de firmas. Un evento que llega en el plazo o después marca la sesión como expired en lugar de aplicar su estado. Un estado no reconocido la marca como unknown en vez de adivinar. El método recover expira localmente una sesión pending, review o unknown cuyo plazo ha pasado: devuelve provider_polled false y nunca contacta a un proveedor. Cualquier valor de permission_granted es un registro local del fixture; live_permission_changed siempre es false.

Escenario hipotético con salidas esperadas

Hipótesis: se crea una sesión sintética fixture-session en el tiempo 0 con timeout de 60 segundos. La llamada al proveedor expira y no llega ningún callback. En el tiempo 61 su worker llama a recover. La salida probada es: mode synthetic_fixture, session fixture-session, status expired, deadline 60, permission_granted false, grant_count 0, live_permission_changed false, policy_version 1, allow_action true, next review_or_authorized_provider_refresh, provider_polled false. Nada se aprobó, y el siguiente paso apunta a revisión humana o a una actualización autorizada del proveedor, no a un reintento automático que asuma éxito. Compare con el camino feliz, también probado: un evento Approved con policy true dentro del plazo produce status approved, permission_granted true, grant_count 1. Repetir el mismo evento devuelve el registro idéntico con grant_count todavía en 1. Una corrección Declined posterior produce status declined, permission_granted false, grant_count 1. Un callback tardío tras la expiración no puede revivir la sesión, porque expired es terminal para los eventos ordinarios.

Manejo de fallos en su propio diseño

Lo siguiente es un diseño de aplicación propuesto, no un comportamiento implementado de GridZen. Trate un timeout de la solicitud como fallo técnico: guarde el resultado HTTP, mantenga la sesión pending y confíe en el plazo persistido, no en un temporizador en memoria. Use reintentos acotados solo donde la operación del proveedor y su flujo lo permitan, y después pase a revisión. Nunca asigne el mismo estado a un timeout, una respuesta malformada, credenciales ausentes o un rechazo del proveedor. Cuando recover devuelva expired, muestre al usuario un mensaje neutral y ofrezca una nueva sesión por su camino normal, o derive a un responsable. Los códigos de error del fixture son comprobaciones útiles del contrato: un evento para una sesión desconocida lanza BINDING_MISMATCH, y leer una sesión desconocida lanza SESSION_NOT_FOUND. Incluso tras approved, la salida de handoff fija verified false y next_action read_current_evidence_and_policy_before_explicit_decision, porque Approved no es un permiso incondicional.

Límites que conviene declarar con claridad

El fixture solo demuestra transiciones de estado locales. No verifica firmas reales, no consulta a ningún proveedor y sus concesiones no son permisos de negocio reales. Para el onboarding alojado de Didit están evidenciadas la creación, el callback firmado y la recuperación autoritativa, pero una persona nueva completando todo el recorrido alojado sigue sin probarse, y la acción real de extremo a extremo sobre un cliente sigue sin verificarse. La disponibilidad de la ruta real requiere confirmación aparte. La prueba HTTP anónima de tres escenarios es un artefacto distinto de este ejemplo descargable; no trate uno como el otro.

Lista de aceptación

Antes de solicitar una integración sandbox, confirme: las sesiones pending persisten con un plazo que sobrevive a un reinicio; un timeout se registra como fallo técnico, separado del resultado de decisión; recover en el plazo o después devuelve status expired, permission_granted false y provider_polled false; un callback tardío o duplicado no cambia grant_count; una corrección Declined revoca la concesión local; los estados desconocidos pasan a unknown, no a approved; se manejan los códigos BINDING_MISMATCH y SESSION_NOT_FOUND; la revisión o el respaldo autorizado tiene un responsable designado; y ninguna línea de log registra un 503 como permiso o rechazo. Si todo esto pasa localmente, el siguiente paso es una solicitud sandbox guardada opcional, no un permiso real.

Ejecutar el ejemplo sintético comprobado

Descargue y extraiga https://gridzen.ai/downloads/verification-delivery.zip, entre en verification_delivery y ejecute con Python 3.10+. El ejemplo local no hace llamadas de red. Use una base nueva para otra prueba de identidad.

python3 delivery.py identity --db /tmp/gridzen-article-fixture.sqlite

Fuentes y alcance

https://gridzen.ai/guides/provider-failures/ https://gridzen.ai/guides/current-capabilities/ Basado en las fuentes comprobadas y el ejemplo local; las reglas propuestas son recomendaciones de diseño, no comportamiento de producción demostrado. Redacción asistida por IA con revisión independiente.