Un diario de respuestas opacas para escrituras de API interrumpidas

El límite del análisis sintáctico

Una escritura en una API puede completarse en el servidor mientras su cliente no logra entender la respuesta. Un estado HTTP exitoso con una estructura JSON desconocida es un ejemplo; una conexión que se pierde a mitad de la respuesta es otro. Ninguna de las dos observaciones, por sí sola, demuestra que el servidor haya rechazado la operación. Un cliente que descarta la respuesta y vuelve a empezar puede perder una credencial devuelta o repetir un cambio que ya se completó.

RFC 9110, sección 9.2.2 distingue la semántica idempotente de una solicitud del mero nombre del método HTTP. Desaconseja repetir automáticamente una solicitud no idempotente si no hay fundamento para saber que repetirla es seguro o que la solicitud original no se aplicó. El procedimiento que sigue propone un registro de evidencia en el cliente para este intervalo de incertidumbre. No hace idempotente a un servicio.

Registrar la intención antes del envío

Asigna un identificador local estable a la operación y persiste el destino, el método, las cabeceras relevantes de la solicitud y una huella del cuerpo exacto de la solicitud. Mantén las credenciales fuera de los resúmenes ordinarios de tareas. Vincula la operación a la cuenta y a la entrada revisada que la autorizan.

La intención duradera debe confirmarse (commit) antes de que comience la escritura por red. Al reiniciar, su existencia significa que el cliente debe examinar el intento guardado antes de plantearse otra escritura. Un registro ilegible es un problema de recuperación, no un permiso para crear una operación de reemplazo.

Conservar los bytes antes de interpretarlos

Captura un sobre de respuesta acotado: estado, URL final, indicador de redirección, tipo de medio, cabeceras relevantes, momento de captura, bytes recibidos, un resumen criptográfico (digest) de esos bytes y un indicador explícito de si la respuesta está completa. Guarda este sobre antes de extraer campos del dominio como un ID de página o una clave de API. Si la lectura se detiene antes de tiempo, conserva los bytes recibidos hasta ese momento con el indicador de completitud en falso. No los rellenes para que parezcan un JSON válido.

Un ejemplo concreto de implementación es el asistente de captura de respuestas de OpenAgentChat en LinkFlow, fijado a una revisión pública. Su función de mutación entrega un sobre acotado a un callback de persistencia antes de devolverlo, y marca como incompleto un cuerpo parcial capturado. Conviene examinar ese límite del callback; sin embargo, esa función por sí sola no establece durabilidad en base de datos, cifrado ni recuperación ante fallos. Esas propiedades requieren código de almacenamiento y pruebas aparte.

Una respuesta puede contener credenciales de un solo uso. Guarda el sobre original en almacenamiento cifrado con control de acceso, con una política de retención acotada y adecuada a la operación. Los diagnósticos públicos deben contener nombres de etapas, tamaños y códigos de error que no sean secretos. Un digest detecta que los bytes han cambiado; no autentica al servidor ni hace seguro divulgar datos secretos.

Promover las conclusiones por separado

Mantén la interpretación del recibo separada de la verificación del resultado público. Un nuevo analizador puede reconocer una respuesta completa que antes era desconocida sin volver a enviar la solicitud. Esa promoción debe conservar el sobre original y registrar qué interpretación se aplicó.

Un recibo puede identificar un recurso para una consulta de solo lectura. Compara la identidad propietaria, el identificador del recurso y el contenido previsto cuando el servicio los exponga. Si la página pública es una representación distinta, comprueba también esa representación. Un tiempo de espera agotado durante esta comprobación deja un paso de verificación sin resolver; no deshace la escritura anterior.

Si no existe ni un recibo utilizable ni una consulta fidedigna, conserva un resultado desconocido de forma explícita. Cualquier acción posterior requiere entonces una decisión de recuperación respaldada por el contrato real de ese servicio. Una clave de solicitud recién generada no es evidencia de que la operación anterior haya fallado.

Casos de fallo que conviene probar

Prueba una carga de éxito desconocida, un cuerpo truncado, una respuesta tardía tras una cancelación, un fallo de persistencia y un reinicio entre la captura y la interpretación. Cuenta las solicitudes de escritura físicas, no solo las llamadas a funciones. Verifica que la recuperación conserve la operación original y que una consulta pública fallida no pueda desencadenar otra solicitud de creación.

Son comprobaciones propuestas, no un benchmark publicado ni una afirmación de ejecución exactly-once universal. El asistente citado es un ejemplo de implementación vinculado al proyecto que contribuye, no un aval de su idoneidad para otro sistema.