API y empresas

Alertar cuando una jurisdicción deja de responder

Un intento fallido no prueba una caída. La diferencia está en el umbral, la ventana y la señal que convierte fallos sueltos en un incidente que alguien puede atender.

Por Marco Ferreiro ·

Torre de comunicaciones metálica en un descampado de llanura, con niebla baja al amanecer y una línea de postes que se pierde en la bruma.

Una consulta que falla no prueba que una jurisdicción se haya caído. Un intento puede vencer por una demora puntual del organismo o por una interrupción de red de nuestro lado, y ese caso aislado ya tiene tratamiento: se reintenta con un presupuesto acotado y, si no cede, la respuesta informa esa fuente como no consultada, según describimos en reintentos y silencios.

La pregunta operativa es cuándo ese conjunto de fallos deja de ser variación normal. Una alerta demasiado sensible avisa cada vez que un portal tarda de más y la guardia la ignora; una demasiado tolerante deja que una fuente esté muda un día entero mientras las respuestas salen incompletas.

Por eso la unidad de la alerta no es la consulta: es una jurisdicción durante una ventana de tiempo. Umbral, confirmación, rearme y contenido del mensaje se derivan de ahí.

Qué cuenta como dejar de responder

Antes del umbral hace falta una clasificación, porque los fallos no son equivalentes:

Las dos últimas ensucian cualquier alerta, porque el transporte dice que todo salió bien: cómo se separa una respuesta real de una que sólo lo parece está en cómo verificamos que una jurisdicción respondió de verdad.

El 429 merece una salida propia: no describe la salud del organismo sino nuestro ritmo, y la acción correcta es espaciar las consultas, no declarar la fuente caída.

La señal necesita un denominador

Contar errores no alcanza. Un umbral absoluto —cincuenta fallos en diez minutos— nunca se cruza en una jurisdicción con pocas consultas diarias y se cruza sin motivo en la de mayor volumen. La señal utilizable es la proporción de observaciones exitosas sobre el total de intentos en la ventana.

Cuando el tráfico no alcanza para formar un denominador estable, hace falta una sonda sintética: una consulta propia, con datos de prueba y frecuencia fija, que garantiza un piso de observaciones para cada jurisdicción del catálogo.

Esa serie se identifica por el código estable de la jurisdicción, no por su nombre visible. Las recomendaciones de nombres y etiquetas de Prometheus advierten que cada combinación de etiquetas define una serie distinta y conviene mantener acotada la cardinalidad; un nombre que cambia de redacción parte el histórico justo cuando hay que comparar.

El silencio no dispara nada por sí solo

Una jurisdicción que dejó de recibir consultas tiene cero errores. Si una configuración la excluye o un despliegue rompe el ruteo, la proporción de éxito se congela o desaparece, y el tablero se ve impecable.

La condición hay que escribirla al revés: la antigüedad de la última observación exitosa. Si ninguna consulta de esa fuente terminó bien dentro del período previsto, eso ya es la alerta. La especificación del SDK de métricas de OpenTelemetry describe cómo se agregan y exportan las mediciones; conviene no confundir una serie que dejó de emitir puntos con una que informa cero.

Umbral, ventana y rearme

Una ventana única produce falsos positivos. Conviene exigir la condición en ventanas consecutivas antes de avisar, y éxitos consecutivos antes de cerrar. Sin esa asimetría, una fuente inestable abre y cierra incidentes cada pocos minutos.

Mientras la condición persiste hay un solo incidente por jurisdicción y clase de falla, no un mensaje por consulta: la clave de agrupación forma parte del diseño, igual que el umbral.

Varios portales tienen además ventanas nocturnas de mantenimiento, y una alerta que se repite todos los días a la misma hora no es un incidente sino un horario: eso se documenta y se contempla en la programación.

Qué lleva la alerta

Un aviso accionable dice qué jurisdicción, desde cuándo, con qué clase de falla predominante, cuándo fue la última observación exitosa y qué está devolviendo la API mientras tanto. Sin ese dato no se puede priorizar: no es lo mismo una fuente marginal que la que sostiene la mayoría de las consultas del día.

Lo que no lleva son patentes, documentos ni CUIT. Un identificador interno de consulta alcanza para reconstruir el caso en un entorno con control de acceso, y el canal de avisos tiene muchos más lectores que ese entorno.

Una alerta que no cambia lo que ve el consumidor es media solución. Mientras el incidente está abierto, esa jurisdicción debería figurar como no disponible en la respuesta y en la cobertura, con el criterio de cómo comunicar fuentes caídas. Y al cerrar hay que verificar dos cosas: que la señal volvió a su rango y que las consultas afectadas se rehicieron.

Metodología

Alcance
Diseño de la señal y del disparo de alertas por indisponibilidad de una fuente jurisdiccional en una integración de consultas de infracciones. No cubre la elección de una herramienta de monitoreo ni la configuración de un proveedor puntual.
Unidad de análisis
Una jurisdicción observada durante una ventana de tiempo, con sus intentos clasificados por resultado y la hora de su última observación exitosa.
Cobertura
Semántica de códigos de estado de RFC 9110 y RFC 6585, y recomendaciones públicas sobre nombres, etiquetas y agregación de métricas de Prometheus y OpenTelemetry, al 29 de agosto de 2026.

Limitaciones

Fuentes

Preguntas frecuentes

¿Cuántos errores seguidos justifican una alerta?

No hay un número universal. Un umbral absoluto nunca se cruza en una jurisdicción con pocas consultas diarias y se cruza por variación normal en la de mayor volumen. Conviene expresar la condición como proporción de observaciones exitosas sobre un denominador conocido y confirmarla en ventanas consecutivas.

¿Una jurisdicción sin consultas aparece como saludable?

Sí, si la señal sólo cuenta errores. Cero consultas producen cero fallos y el tablero se ve impecable. Por eso la condición debe incluir la antigüedad de la última observación exitosa, que detecta tanto la caída de la fuente como el ruteo que dejó de enviarle trabajo.

¿Un 429 del portal significa que la jurisdicción está caída?

No. Según RFC 6585 ese código informa que se excedió una política de solicitudes, algo que describe nuestro ritmo antes que la salud del organismo. La acción razonable es espaciar las consultas y tratarlo como una clase de falla distinta.

¿La alerta puede incluir la patente de la consulta que falló?

No hace falta. Un identificador interno de consulta permite reconstruir el caso en un entorno con control de acceso, sin poner patente, documento ni CUIT en un canal de avisos que suele tener muchos lectores.

Notas relacionadas