Timeout no significa “sin multas”: cómo informar resultados parciales en una integración
Cuando una fuente no responde, el resultado es parcial o indeterminado, nunca cero. Un contrato explícito permite reintentar, alertar y decidir sin producir falsos negativos.
Por Marco Ferreiro ·
Una API que consulta varias fuentes puede recibir tres actas válidas y, al mismo tiempo, agotar el tiempo de espera de otra jurisdicción. Devolver una lista vacía para la fuente que falló parece simple, pero cambia el significado: transforma “no sabemos” en “no hay”.
Ese falso negativo puede frenar una alerta, habilitar una compra o cerrar una tarea sin evidencia suficiente.
Separá resultado de cobertura
El contrato necesita dos dimensiones:
- resultado: actas informadas y normalizadas por las fuentes que respondieron;
- cobertura: estado de cada fuente que se esperaba consultar.
Una respuesta global puede contener actas y seguir siendo parcial. Del mismo modo, una lista vacía sólo representa “sin actas informadas” cuando la cobertura requerida está completa.
Modelá estados explícitos
Para cada fuente conviene distinguir, como mínimo:
completed: respuesta válida, con o sin actas;timeout: no cerró dentro del presupuesto;failed: error no interpretable como respuesta de negocio;not_applicable: una regla versionada determinó que no correspondía consultar;pending: todavía no alcanzó un estado terminal.
El agregado puede ser complete, partial o failed. Evitá que el consumidor tenga que deducirlo mirando mensajes de texto.
Un timeout no borra respuestas válidas
Si otras fuentes terminaron, devolvé sus resultados con su procedencia. Marcá la consulta como parcial, listá la fuente faltante con un código estable y aclarale al usuario que puede haber información no verificada.
No muestres “0 multas”. Una interfaz puede decir: “Se encontraron 3 actas en las fuentes que respondieron; 1 fuente no pudo verificarse”. Sin números inventados en documentación pública, el patrón sigue siendo el mismo.
Reintentá sin duplicar
El reintento debe continuar la misma consulta lógica. Usá una clave idempotente y registrá intentos técnicos por separado. Aplicá espera creciente, variación aleatoria y un límite claro para no sobrecargar a la fuente.
Cuando un reintento completa la cobertura:
- agregá o actualizá el estado de esa fuente;
- recalculá el estado global;
- emití sólo los eventos semánticos nuevos;
- preservá el historial anterior.
No envíes una segunda alerta por la misma acta sólo porque llegó en otro intento.
Diseñá respuestas accionables
Una respuesta parcial debería incluir:
- identificador de consulta apto para soporte;
- fecha de corte;
- estado global;
- resultados y fuente de procedencia;
- fuentes completadas y faltantes;
- si el sistema reintentará y hasta cuándo;
- recomendación segura para el consumidor.
No expongas credenciales, URLs internas ni cuerpos crudos de terceros. Los logs detallados deben permanecer protegidos y vinculados mediante un identificador.
Métricas que revelan el problema
Medí tasa de finalización por fuente, latencia, timeouts, reintentos y antigüedad de la última respuesta válida. Separá el porcentaje de consultas con actas del porcentaje de consultas completas.
Si el denominador incluye parciales como si fueran completas, la métrica de “vehículos sin multas” mejora artificialmente cuando una fuente se cae. Esa es exactamente la conducta que el modelo de cobertura evita.
Comunicación para personas, no sólo máquinas
El código PARTIAL_SOURCE_TIMEOUT ayuda a una integración. La interfaz, en cambio, debe explicar: “No pudimos verificar una de las fuentes. Los resultados mostrados no cubren esa jurisdicción”.
También necesita una acción: reintentar, recibir una notificación o consultar el organismo. Ocultar el fallo detrás de un cero impide decidir.
Privacidad y retención
Registrá sólo los datos necesarios para reproducir el estado. La Ley 25.326 exige calidad, pertinencia y finalidad en el tratamiento de datos personales. Definí plazos de retención y no guardes cuerpos completos si alcanzan hashes, campos normalizados y logs redactados.
Regla de cierre
“Sin multas” es una conclusión de negocio. “Timeout” es un estado técnico. Un sistema confiable nunca usa el segundo como prueba del primero. Conserva lo que sabe, señala lo que falta y permite completar la verificación sin perder trazabilidad.
Metodología
- Alcance
- Diseño de contratos y operación para integraciones que agregan respuestas de múltiples fuentes de infracciones.
- Unidad de análisis
- Una consulta lógica con estados individuales por fuente, intentos técnicos y una evaluación global de cobertura.
- Cobertura
- Principios de calidad, trazabilidad y minimización; los códigos y plazos concretos dependen del contrato de la API.
Limitaciones
- No prescribe un protocolo de terceros ni garantiza disponibilidad de una jurisdicción particular.
- Los umbrales de timeout y reintento deben calibrarse con evidencia operativa y límites del proveedor.
Fuentes
- CENAT — Certificado Nacional de Antecedentes de Tránsito — Agencia Nacional de Seguridad Vial (consultada el )
- Guía para la publicación de datos en formatos abiertos — Dirección de Datos Abiertos (consultada el )
- Ley 25.326 de Protección de los Datos Personales — Argentina.gob.ar (consultada el )
- Política de privacidad de la Agencia de Acceso a la Información Pública — Agencia de Acceso a la Información Pública (consultada el )
Preguntas frecuentes
¿Debo descartar las actas obtenidas si otra fuente tuvo timeout?
No. Podés devolverlas como evidencia parcial, siempre que identifiques qué fuentes respondieron, cuál falló y que el resultado global no es completo.
¿Cuándo conviene reintentar una fuente que no respondió?
Con una política acotada, idempotente y con espera creciente. El reintento debe completar la operación original y no crear consultas o alertas duplicadas.
Notas relacionadas
Cómo definimos una consulta completa antes de publicar estadísticas de multas.ar
Antes de convertir consultas operativas en porcentajes o rankings, exigimos cobertura identificable, respuestas comparables y controles que separen un resultado válido de un fallo técnico.
Una consulta vacía no es un libre deuda: qué verificamos y qué no
Que una consulta no muestre actas sólo describe lo que respondieron determinadas fuentes en ese momento. No reemplaza un certificado ni prueba por sí sola que no exista deuda.
Polling de consultas sin saturar la API: Retry-After, ETag y espera con jitter
Consultar el estado cada segundo no hace que una búsqueda termine antes. Un contrato con Retry-After, ETag y una espera aleatoria reduce solicitudes repetidas, bytes y picos de clientes sincronizados.