Cloudflare añade reintentos para Durable Objects y los distingue según el coste del error

Si una llamada a un Durable Object terminaba con un fallo de red, antes a menudo el desarrollador tenía que decidir si volver a enviarla. Desde el 5 de noviembre de 2026, el runtime de Cloudflare gestiona algunos de esos reintentos: repite automáticamente determinadas llamadas fetch() y RPC a través de un stub. Para el código de la aplicación, la pregunta clave ahora es más precisa: ¿puede ejecutarse de nuevo, de forma segura, este método en particular?

La respuesta depende de dónde se interrumpió la conexión. El runtime reintenta automáticamente algunas llamadas y, de forma predeterminada, mantiene la protección frente a la doble ejecución. Si la entrega es incierta, utiliza el mismo identificador de solicitud y el objeto rechaza el reintento si ya recibió el primer intento. Un método marcado explícitamente con retryable() se comporta de otra manera: puede volver a ejecutarse aunque el primer intento ya haya llegado al objeto. Por eso, esta marca solo conviene para operaciones cuyo reintento sea seguro tanto para el estado como para los efectos secundarios.

Qué reintenta exactamente el runtime

Según el anuncio de Cloudflare del 5 de noviembre, los reintentos se aplican a las llamadas fetch() y RPC a Durable Objects realizadas por un Worker u otro Durable Object. Para las llamadas a través de un stub se prevé de forma predeterminada un primer intento y hasta cuatro reintentos; no se inician nuevos intentos una vez transcurridos 10 segundos desde el comienzo de la llamada.

La condición es que el error tenga la propiedad .retryable. Por ejemplo, puede que la solicitud no llegara al objeto porque este se estaba reiniciando o trasladando. El runtime también puede volver a intentarlo si se interrumpe la conexión y no es posible determinar si el objeto llegó a aceptar la solicitud. Si el objeto ya la recibió, se rechaza el reintento con el mismo identificador. El runtime no reintenta los errores lanzados por el código del Durable Object, los errores con .overloaded ni las respuestas HTTP como 500: son respuestas del manejador, no errores de entrega.

Por qué reintentar la entrega no equivale a repetir la operación

Volver a transmitir una solicitud no implica, por sí solo, que el método se ejecute una segunda vez. Cuando el resultado es incierto, el runtime envía la solicitud con el mismo identificador; si el objeto aceptó el primer intento, rechaza el reintento. En el comportamiento normal, esto evita que un único fallo de red haga que el método se ejecute de nuevo, por ejemplo, que vuelva a cobrar o a crear un registro.

El límite cambia cuando el método se marca mediante retryable() de cloudflare:durable-objects. En ese caso, se permite que el objeto vuelva a ejecutar el método aunque el primer intento pudiera haber comenzado. Cloudflare da dos ejemplos: asignar a un producto una cantidad determinada es idempotente; aumentar la cantidad en una unidad no lo es. Repetir la primera acción establece el mismo valor; repetir la segunda añade otra unidad.

Hay que revisar no solo el estado final del almacenamiento, sino también todos los efectos del método. Si un reintento crea otro pago, envía un mensaje o activa una acción externa, que el estado interno del Durable Object no cambie no basta para que el reintento sea seguro. La marca es adecuada cuando repetir la operación no altera el significado del resultado ni duplica los efectos secundarios.

Cuándo resulta útil la idempotencia explícita

Asignar un valor, guardar una instantánea del estado o actualizar un campo a un valor conocido suele producir el mismo resultado al repetirse. Para esos métodos, retryable() puede permitir que la llamada termine correctamente tras una interrupción de la conexión que se produzca una vez iniciada la ejecución.

Las operaciones «sumar», «crear otra», «cobrar» y «enviar» suelen necesitar otra protección. Antes de permitir que se ejecuten de nuevo, asegúrate de que la operación de negocio reconoce los duplicados o está diseñada de tal forma que el reintento no produzca un segundo efecto. El nombre de la función no garantiza nada: revisa todos los cambios de estado y las acciones externas que realiza el método.

retryable() tiene una función limitada: permite volver a ejecutar el método cuando no se puede determinar si la primera llamada llegó. No cambia los tipos de error a los que responde el runtime ni aumenta el número de intentos. La marca se aplica a la función; una versión sobrescrita o envuelta del método no la hereda automáticamente, salvo que también se marque explícitamente.

Qué revisar en un proyecto que ya está en producción

El lugar más probable que conviene auditar son los ciclos de reintentos propios alrededor de las llamadas a Durable Objects. Ahora cada intento puede incluir los reintentos del runtime, por lo que el número total de llamadas podría ser superior al que determina únicamente la aplicación. Cloudflare recomienda reducir el número de intentos propios o establecer maxRetries: 0 para el stub si tu código gestiona los reintentos.

Los límites de un stub específico se configuran al llamar a get() o getByName(). El parámetro maxRetries permite establecer entre cero y diez reintentos tras el primer intento; timeoutMs define el intervalo tras el cual ya no se inician nuevos intentos, entre 500 y 60 000 milisegundos. Estos ajustes se aplican a las llamadas realizadas a través de ese stub. Las funciones retryable() y el objeto retry requieren Wrangler 4.158.0 o posterior.

Una revisión útil plantea tres preguntas para cada llamada: ¿puede modificar el estado más de una vez?, ¿puede repetir efectos secundarios externos?, ¿tiene la aplicación una política de reintentos propia? Después, decide si ese stub debe utilizar los valores predeterminados o límites personalizados. En los métodos idempotentes, puedes valorar por separado si conviene marcarlos explícitamente; para los demás, mantén la protección y revisa cómo se gestiona el error cuando se desconoce el resultado del primer intento.

La consecuencia: la responsabilidad se desplaza al límite del método

El reintento automático elimina parte de la lógica de red del código de la aplicación, pero decidir si se puede repetir la ejecución sigue siendo una propiedad de la operación. El runtime puede reintentar la entrega de forma segura y detenerse si no sabe si la llamada llegó a ejecutarse. El desarrollador puede permitir que se repita el método, confirmando expresamente que no duplicará cambios de estado ni efectos secundarios.

Por eso, conviene leer esta actualización como un cambio en el contrato entre la capa de transporte y el manejador. Primero, revisa los ciclos de reintentos propios y la repetibilidad de los efectos secundarios; después, configura los límites de los stubs necesarios. Así, la resistencia integrada frente a fallos breves puede combinarse con el control sobre las operaciones en las que una segunda ejecución tiene un coste real.