API y empresas

Colas de trabajo para consultas largas

Aceptar una consulta que tarda minutos obliga a decidir dónde queda ese trabajo mientras nadie lo mira. La cola interna define reintentos, prioridad y qué se pierde cuando un proceso muere.

Por Marco Ferreiro ·

Hilera de cajones de madera idénticos alineados sobre el piso de cemento de un depósito, junto a carros de carga vacíos, con luz natural lateral.

Detrás de un 202 Accepted queda una pregunta que el contrato HTTP no responde: dónde vive ese trabajo mientras nadie lo mira. Una consulta sobre varias jurisdicciones puede durar minutos, sobrevivir al reinicio del proceso que la aceptó y competir con el lote que otra empresa envió un segundo antes.

La cola de trabajo es esa pieza intermedia: la estructura que guarda lo aceptado, lo reparte entre trabajadores y decide qué ocurre cuando uno falla. Es infraestructura interna, pero sus decisiones se ven desde afuera, en cuánto tarda una respuesta y en qué se informa cuando algo no sale.

Esta nota mira ese lado interno; el contrato visible hacia el cliente ya está en consultas largas en una API.

El trabajo vive en la base, no en el mensaje

RFC 9110 define 202 como una solicitud aceptada cuyo procesamiento no terminó, y espera que la representación devuelta describa el estado actual. Para describirlo hace falta un registro durable escrito antes de responder: identificador opaco, alcance pedido, quién lo pidió, estado y marcas de tiempo.

El mensaje encolado es un aviso, no el trabajo. Si la cola pierde un mensaje, el registro sigue y puede reprogramarse; si el mensaje lleva la única copia del pedido, vaciar la cola borra consultas que el cliente ya considera aceptadas.

Esa separación mantiene el dato sensible fuera del transporte: el trabajador lee de la base lo que necesita, con sus propios permisos.

Al menos una vez, y por eso pasos repetibles

Un trabajador reserva un trabajo por un tiempo acotado y lo confirma al terminar. Si el proceso muere a mitad, la reserva vence y otro lo retoma. Ese esquema entrega al menos una vez: un trabajo puede ejecutarse dos veces sin que nadie se haya equivocado.

La consecuencia es concreta. Los resultados se escriben por clave de consulta, fuente y acta, no insertando filas nuevas; el pasaje a un estado terminal se condiciona al anterior; y todo efecto hacia afuera, como una notificación o un cargo, lleva su clave de idempotencia.

La reserva debe durar más que el paso más lento previsto. Si queda corta, dos trabajadores corren en paralelo sobre el mismo trabajo. Renovarla mientras hay progreso es preferible a fijar un bloqueo enorme por las dudas.

Una cola sola no reparte bien

Con una única fila, un lote de miles de patentes hace esperar a la consulta individual que llegó después. Conviene separar colas por clase de trabajo, interactiva y masiva, y limitar la concurrencia por cliente para que ninguno tome todos los trabajadores.

El mismo criterio vale por fuente: si un organismo responde lento, un cupo propio evita que sus tareas ocupen toda la capacidad.

Cuando el pendiente supera lo que puede procesarse en un horizonte razonable, aceptar más es prometer algo que no se va a cumplir. Conviene rechazar temprano e indicar cuándo reintentar; RFC 9110 prevé Retry-After para eso. El borrador del IETF sobre campos RateLimit propone publicar la política de uso, pero al 29 de agosto de 2026 sigue siendo un Internet-Draft y no una garantía de admisión.

Reintentos con techo y un destino para lo que falla

Cada trabajo lleva contador de intentos, espera creciente y un tope. Distinguir el error transitorio del permanente evita dos daños opuestos: reintentar para siempre una credencial revocada o abandonar por un corte de red breve.

Agotado el tope, el trabajo pasa a un estado terminal de falla y a un destino de descartes con motivo, último error e identificadores de traza. Ese destino se revisa como parte de la operación, no cuando alguien reclama.

Hacia el cliente conviene publicar el error con un formato estable. RFC 9457 define un cuerpo con tipo, título, estado y detalle, y admite campos propios; separa “la consulta falló” de “una fuente falló”, que es un resultado parcial y no un fracaso.

Qué medir y qué probar antes de prometer un tiempo

El tamaño de la cola dice poco: una fila corta con un trabajo trabado hace horas es peor que una larga que avanza. Las señales útiles son la antigüedad del pendiente más viejo, el tiempo entre aceptación y estado terminal y la cantidad de reintentos, abiertos por clase y por cliente. W3C Trace Context define traceparent y tracestate para propagar el contexto de una traza entre servicios; guardarlos al aceptar el trabajo une la llamada inicial con una ejecución muy posterior. Las etiquetas de métricas no llevan patente ni CUIT.

Cuatro pruebas dicen más que un diagrama: matar un trabajador a mitad y confirmar que el trabajo se retoma sin duplicar; encolar dos veces la misma clave y verificar que hay un solo registro; llenar la cola con un lote grande y comprobar que la consulta interactiva sigue respondiendo; forzar la falla permanente de una fuente y revisar que termina en descartes con motivo legible.

Una cola bien diseñada no promete velocidad: promete que nada aceptado se pierde en silencio y que, cuando algo tarda o falla, se puede decir cuál trabajo es, desde cuándo y por qué.

Metodología

Alcance
Diseño de la cola interna que ejecuta consultas asincrónicas de infracciones sobre varias fuentes, sin recomendar un motor de colas ni un proveedor en particular.
Unidad de análisis
Un trabajo aceptado, con su registro durable, sus intentos de ejecución y la transición hasta un estado terminal.
Cobertura
Semántica HTTP de aceptación y espera, formato estándar de errores, propagación de contexto de traza y campos de límite de uso en discusión al 29 de agosto de 2026.

Limitaciones

Fuentes

Preguntas frecuentes

¿Se puede garantizar que un trabajo se ejecute una sola vez?

En la práctica no conviene diseñar suponiéndolo. Si un trabajador puede morir después de terminar su tarea y antes de confirmarla, el trabajo vuelve a repartirse. Lo alcanzable es que la repetición no cambie el resultado: escrituras por clave, transiciones condicionadas al estado anterior y efectos externos con marca de intento.

¿Alcanza con mirar cuántos trabajos hay en la cola?

Es una señal incompleta. Una cola corta con un trabajo detenido hace horas es peor que una cola larga que avanza. La medición útil combina la antigüedad del pendiente más viejo con el tiempo desde la aceptación hasta el estado terminal, separado por clase de trabajo y por cliente.

¿Conviene una sola cola para todos los clientes?

Una cola única deja que un lote grande demore consultas chicas que llegaron después. Separar por clase de trabajo y limitar la concurrencia por cliente y por fuente evita ese bloqueo sin necesidad de un esquema de prioridades complejo.

¿Qué pasa con un trabajo que agota sus reintentos?

Debería terminar en un estado terminal explícito y en un destino de descartes con motivo, último error e identificadores de traza. Ese destino tiene que revisarse: una cola de descartes que nadie mira convierte una falla visible en una pérdida silenciosa.

Notas relacionadas