Consultas largas en una API: cuándo responder 202 y cómo exponer el estado
HTTP 202 confirma aceptación, no finalización. Una integración útil devuelve una operación consultable, transiciones explícitas, resultado parcial y una cancelación con semántica definida.
Por Marco Ferreiro ·
Consultar infracciones en varias fuentes puede durar más que la conexión de un cliente. Mantener un POST abierto hasta que responda el último organismo vuelve frágil la integración: un proxy puede cortar la conexión aunque el servidor continúe trabajando.
HTTP 202 permite separar aceptación y resultado. Pero el código solo no alcanza. Hace falta un recurso que represente la operación y permita saber qué terminó, qué sigue pendiente y qué se canceló.
Cuándo corresponde responder 202
RFC 9110 define 202 Accepted como una solicitud aceptada para procesamiento cuya ejecución no terminó. También aclara que el procesamiento puede no haber empezado y que finalmente puede ser rechazado. Por eso no es un “200 diferido”.
El patrón sirve cuando el servidor valida y acepta trabajo durable, pero no puede entregar una representación final dentro del tiempo de la llamada. Antes de responder debe haber persistido suficiente información para continuar aunque el proceso o la instancia se reinicien.
Si la operación ya terminó, corresponde devolver su resultado. Si la solicitud es inválida o no fue aceptada, un 202 sólo posterga un error que ya se conoce.
Qué debería devolver la aceptación
La respuesta puede incluir Location: /operations/{id} y un cuerpo mínimo:
{
"operationId": "op_opaque",
"status": "accepted",
"statusUrl": "/operations/op_opaque"
}
El identificador debe ser opaco y no contener patente, CUIT ni información de la empresa. El recurso necesita autorización igual o más estricta que el resultado que protege.
RFC 7240 define la preferencia respond-async: un cliente puede expresar que acepta manejo asíncrono. También existe wait, que comunica cuánto está dispuesto a esperar. Son preferencias, no órdenes; el contrato debe explicar si las admite.
Una máquina de estados pequeña y explícita
Una operación de consulta puede usar:
accepted: guardada y todavía no iniciada;running: al menos una fuente está en ejecución;completed: todas las fuentes previstas alcanzaron un estado terminal válido;partial: hay resultados, pero alguna fuente no completó;failed: no existe un resultado utilizable bajo la regla del producto;cancellation_requested: se pidió detener trabajo futuro;cancelled: el sistema ya no iniciará nuevas tareas para la operación.
Los estados deben tener transiciones documentadas. partial no se deriva sólo de que haya menos actas: depende de la cobertura. failed tampoco significa “sin multas”.
Polling sin convertirlo en una carga nueva
El cliente consulta el mismo statusUrl, no repite el POST original. La respuesta puede incluir Retry-After, un tiempo estimado cuando exista evidencia y un ETag para evitar transferir una representación sin cambios.
El servidor debería limitar la frecuencia y responder de forma consistente. Un 404 requiere semántica clara: puede significar identificador inexistente, falta de autorización o expiración, pero no debería revelar operaciones de otra empresa.
Cuando termina, el recurso enlaza el resultado. OpenAPI permite describir vínculos entre una respuesta y otra operación; documentar ese recorrido ayuda a generar clientes y pruebas de contrato.
Resultados parciales por fuente
La representación de estado debe separar el progreso técnico de la información encontrada. Un ejemplo conceptual puede informar 2 completed, 1 failed y 1 running, sin devolver datos sensibles en una lista pública.
Cada fuente necesita un estado terminal, momento de última actualización y categoría de error. Si una devolvió dos actas y otra tuvo timeout, el resultado no es “dos multas totales”: son dos hallazgos dentro de una cobertura parcial.
El recurso final puede conservar el mismo identificador para que auditoría, callback y descarga hablen de la misma operación.
Cancelación es una petición, no una máquina del tiempo
El cliente puede solicitar DELETE /operations/{id} o una acción explícita de cancelación. La API debe decidir qué significa: impedir nuevas fuentes, intentar interrumpir tareas en curso o ambas. Una tarea externa ya enviada puede no ser cancelable.
Si la operación termina al mismo tiempo que llega la solicitud, el servidor debe devolver el estado real. No conviene borrar resultados ni historial sólo para que la interfaz diga “cancelado”. La cancelación de mejor esfuerzo puede dejar hallazgos completados y marcar qué trabajo se omitió.
Además, cancelar procesamiento no equivale a ejercer un derecho de eliminación de datos; retención y privacidad tienen políticas propias.
Errores y callbacks que se puedan reconciliar
RFC 9457 ofrece un formato estándar para explicar errores HTTP con type, title, status, detail e instance. Los códigos internos pueden extenderlo sin exponer trazas ni secretos. La operación, por su parte, debería guardar una categoría estable que el cliente pueda automatizar.
Un callback reduce polling, pero debe ser idempotente y admitir reintentos. OpenAPI permite describir callbacks iniciados por el proveedor. Aun así, el cliente necesita el statusUrl: si el aviso se pierde, consulta y reconcilia.
La prueba que demuestra el contrato
Una suite mínima crea una operación, comprueba el 202 y su Location, observa una transición, solicita cancelación y verifica un estado terminal. También simula una fuente lenta, una caída parcial, un callback duplicado y acceso cruzado entre empresas.
En una API de infracciones, el objetivo no es terminar rápido a cualquier costo. Es permitir que el cliente sepa cuándo el trabajo fue aceptado, qué cobertura obtuvo y si una cancelación realmente tuvo efecto. HTTP 202 abre ese circuito; el recurso de operación lo vuelve verificable.
Metodología
- Alcance
- Diseño de un contrato HTTP asíncrono para consultas multi-fuente sin confundir aceptación, transporte, trabajo y resultado de negocio.
- Unidad de análisis
- Cada operación lógica creada por el cliente, separada de sus solicitudes HTTP, intentos internos por fuente y entregas de notificación.
- Cobertura
- Semántica de HTTP, preferencias asíncronas, descripción OpenAPI y formato de errores vigentes al 14 de agosto de 2026.
Limitaciones
- Los estándares no definen una máquina de estados ni una garantía de cancelación universal; ambas deben especificarse en cada API.
- El patrón requiere almacenamiento durable y control de acceso, decisiones de infraestructura que no quedan resueltas por devolver un código 202.
Fuentes
- RFC 9110 — HTTP Semantics — RFC Editor (consultada el )
- RFC 7240 — Prefer Header for HTTP — RFC Editor (consultada el )
- OpenAPI Specification 3.1.1 — OpenAPI Initiative (consultada el )
- RFC 9457 — Problem Details for HTTP APIs — RFC Editor (consultada el )
Preguntas frecuentes
¿HTTP 202 significa que la consulta terminará correctamente?
No. RFC 9110 define que fue aceptada para procesamiento, que puede no haber comenzado y que finalmente puede fallar. El resultado se conoce siguiendo la operación, no interpretando el 202 como éxito final.
¿Dónde debería estar la URL para consultar el estado?
Puede viajar en `Location` y también en una representación de la operación. El contrato debe documentarla de forma estable, indicar autenticación y evitar que el identificador exponga una patente u otro dato sensible.
¿Cancelar una operación debe borrar los resultados ya obtenidos?
No necesariamente. Cancelar puede impedir trabajo futuro mientras conserva evidencia y hallazgos completados. La API debe declarar si es mejor esfuerzo, qué estados admiten la solicitud y qué retención aplica.
¿Un callback elimina la necesidad de consultar el estado?
No conviene depender sólo del callback. Puede fallar o duplicarse. Un recurso consultable permite reconciliar la entrega y conocer el estado final aunque el aviso no llegue.
Notas relacionadas
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.
Cobertura de una API: cómo comunicar fuentes caídas y resultados parciales
Una integración de infracciones necesita informar qué fuentes respondió, cuáles fallaron y si el resultado es completo. Un cero sin cobertura comprobada puede inducir decisiones incorrectas.
Webhooks de nuevas multas: idempotencia, reintentos y trazabilidad
Un webhook confiable puede llegar más de una vez, demorarse o fallar después de ser procesado. El diseño debe deduplicar eventos, reintentar con límites y conservar evidencia de punta a punta.