Consulta parcial: qué devolver si falla una fuente

Detectar que una jurisdicción no cerró es la parte fácil. Que ese hueco no puede devolverse como un cero es una decisión ya tomada, y está desarrollada en timeout no significa sin multas. Lo que queda abierto es más concreto: qué sale exactamente del servidor en el momento de contestar.

Esa respuesta se decide en dos planos: el código HTTP y su relación con el cuerpo, y qué campos sobreviven a una cobertura incompleta. Hay además una pregunta previa que no le corresponde a la API: si una parcial le sirve a quien consulta.

206 no es el código de una consulta parcial

RFC 9110 define 206 Partial Content como la respuesta a una solicitud de rango satisfecha: transfiere una o más partes de la representación seleccionada. Reutilizarlo para decir “faltó una jurisdicción” invita a que cachés, proxies y clientes lo lean con la semántica que sí está especificada. El nombre coincide con la idea; el significado, no.

El extremo opuesto tampoco sirve. RFC 9110 define la clase 5xx como el reconocimiento de que el servidor erró o no puede cumplir el método pedido; 502 y 504 describen a un intermediario que recibió una respuesta inválida, o ninguna a tiempo. Contestar así descarta actas que ya están obtenidas.

Queda un camino sobrio: un código que describa el destino de la solicitud como un todo, más un cuerpo con un estado global explícito y documentado. La condición innegociable es que ambos no se contradigan y que una parcial nunca resulte indistinguible de una completa para un cliente que no lea texto libre.

Quién decide si una parcial alcanza

La API no sabe qué va a hacer el consumidor con el hueco. Un control previo a una transferencia puede exigir cobertura completa; un tablero de flota puede convivir con una fuente faltante durante horas. El mismo fallo admite dos devoluciones legítimas.

Esa tolerancia debería viajar en la solicitud y no adivinarse. RFC 7240 define una preferencia de manejo estricto o tolerante —rechazar la solicitud ante un problema o intentar procesarla igual— y un encabezado para informar qué preferencias se aplicaron. El caso que contempla es el error en la propia solicitud, no la caída de un tercero: el contrato tiene que definir ese alcance o exponer un parámetro propio. Importa el orden: el cliente declara antes, el servidor informa qué régimen usó.

Con criterio estricto, la ausencia de una fuente requerida produce un error que no borra lo obtenido pero tampoco entrega un veredicto. Con criterio tolerante, produce una parcial.

Lo que se devuelve y lo que se retira

Las actas obtenidas se devuelven con su procedencia y su fecha de obtención. La parte que suele olvidarse es la inversa: los campos derivados se retiran. Total de deuda, cantidad de actas, antigüedad de la más vieja, semáforos y banderas del tipo “sin deuda informada” se calculan sobre un denominador incompleto. No quedan aproximados; quedan mal.

Retirar no es poner cero. Un campo ausente obliga al consumidor a decidir qué hacer; un cero atraviesa sin ruido todas las capas siguientes. La diferencia está trabajada en null, ausente o cero.

Una prueba barata: poné una parcial al lado de una completa y fijate si algún consumidor puede renderizarlas igual. Si puede, falta un campo obligatorio en la parcial, no una advertencia en la interfaz.

El fallo de una jurisdicción es un objeto, no un mensaje

Que la respuesta lleve una capa de problemas ya está planteado en cobertura de una API. Acá se decide su forma: una entrada por cada jurisdicción que no cerró, y no un mensaje global.

RFC 9457 aporta el vocabulario —tipo, estado, título, detalle e instancia— y advierte que el detalle debería ayudar a corregir el problema antes que dar información de depuración. La especificación prevé trasladar ese modelo a otros formatos, pero no cubre su uso dentro de una respuesta exitosa: incorporarlo así es una decisión del contrato, y hay que documentarla.

Cada entrada debería identificar a la fuente por un código estable y no por su nombre visible, distinguir el tipo de fallo y ofrecer una acción. Del organismo no viaja nada crudo: para soporte alcanza un identificador de correlación opaco.

Qué verificar antes de publicar el contrato

Una parcial, además, tiene que poder completarse: necesita una identidad estable de consulta, para que un reintento actualice ese objeto en lugar de crear otro. La marca de parcial también tiene que sobrevivir al viaje. Si una exportación, un caché o una notificación la pierden, el hueco vuelve a ser un cero, esta vez sin nadie que pueda notarlo.

Antes de publicar, revisá:

que ninguna jurisdicción faltante quede reducida a un mensaje de texto;
que ningún agregado se calcule sobre cobertura incompleta;
que el código HTTP y el estado del cuerpo digan lo mismo;
que el cliente pueda declarar su tolerancia antes de consultar.

Una jurisdicción caída no es una rareza que se resuelve improvisando: es un estado previsible, y la respuesta de la API decide si la falla se detiene ahí o sigue viajando disfrazada de resultado.

Metodología

Alcance: Diseño de la respuesta que devuelve una API de infracciones cuando una de las fuentes previstas no alcanza un estado terminal. No cubre la política de reintentos ni el modelo interno de cobertura.
Unidad de análisis: Una respuesta HTTP a una consulta lógica con al menos una jurisdicción sin cerrar.
Cobertura: Semántica HTTP de 206 y de los errores de servidor, formato estándar de problemas y preferencias de manejo declaradas por el cliente. No describe el comportamiento de un organismo en particular.

Limitaciones

La preferencia de manejo del estándar fue pensada para los errores de la propia solicitud; extenderla a la tolerancia de cobertura exige definir ese alcance en el contrato.
RFC 9457 no cubre el uso de su modelo dentro de una respuesta exitosa: incorporarlo como lista de problemas por jurisdicción es una decisión del contrato y hay que documentarla.
El código HTTP concreto depende del contrato de cada API. Acá se descarta un uso y se fija una condición de coherencia, no un valor único.
Retirar campos derivados puede romper clientes que ya los asumían presentes, así que el cambio necesita versionado y aviso previo.

Fuentes

RFC 9110 — HTTP Semantics — RFC Editor (consultada el 2026-08-29)
RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el 2026-08-29)
RFC 7240 — Prefer Header for HTTP — RFC Editor (consultada el 2026-08-29)

Preguntas frecuentes

¿Sirve devolver 206 cuando falta una jurisdicción?

No conviene. RFC 9110 define 206 como la respuesta a una solicitud de rango satisfecha: transfiere una o más partes de la representación seleccionada. El nombre coincide con la idea de parcialidad, pero la semántica especificada es otra, y las cachés, los proxies y las bibliotecas cliente que siguen la especificación pueden interpretarla así. El estado parcial se expresa en el cuerpo, con un campo documentado.

¿Hay que descartar las actas encontradas si una fuente falló?

No. Se devuelven con su procedencia y su fecha de obtención. Lo que se retira son los campos derivados de esas actas —totales, conteos, veredictos—, porque se calcularían sobre una cobertura que no está completa.

¿Por qué no devolver el total en cero mientras falta una fuente?

Porque un cero es un valor válido que atraviesa sin ruido todas las capas siguientes y termina impreso en un informe. Un campo ausente, en cambio, obliga al consumidor a decidir qué hacer con el hueco.

¿Puede la API decidir sola si una respuesta parcial sirve?

No sabe lo suficiente. Un control previo a una transferencia puede exigir cobertura completa y un tablero de flota puede convivir con una fuente faltante. La tolerancia debería declararla el cliente en la solicitud, y la respuesta debería decir qué criterio se aplicó.

Consulta parcial: qué devolver cuando una jurisdicción falla