Todo desarrollador backend en Go tarde o temprano se topa con los caprichos de las redes distribuidas: un corte breve de conexión TCP, un timeout de un proxy perimetral o el reinicio de un pod en Kubernetes. En el cliente estándar net/http, reintentar una petición fallida no es tan sencillo: el flujo de datos req.Body se cierra y se lee hasta el final en el primer intento, y la segunda llamada falla con el error http: Request.Body already consumed.
Para no reinventar la rueda con búferes de bytes, la comunidad suele recurrir a la probada biblioteca go-retryablehttp de HashiCorp. Envuelve con cuidado el transporte estándar, sabe rebobinar io.ReadSeeker y reintenta automáticamente el envío ante códigos 500, 502, 503 y 504.
Sin embargo, aquí se esconde una ilusión peligrosísima: la repetibilidad del transporte (transport retryability) no tiene nada que ver con la idempotencia de la aplicación (application idempotence).
La trampa del parámetro RetryMax y los cortes de respuesta
El primer tropiezo poco evidente de la biblioteca está en la aritmética de los intentos. Cuando configuras el parámetro retryClient.RetryMax = 2, es fácil pensar que el servicio ejecutará exactamente dos peticiones. En realidad, el parámetro indica la cantidad de reintentos tras el primer envío fallido. Es decir, el cliente hará hasta tres peticiones: una original más dos reintentos. Si una API externa cobra por petición o tiene límites estrictos de frecuencia (rate limits), ese intento extra puede convertirse en una sorpresa desagradable.
El segundo problema es mucho más grave y afecta a los métodos mutantes (POST, PATCH). Imagina un escenario de cobro o creación de pedido:
- El cliente envía una petición POST con el cuerpo del pedido al servidor de la pasarela de pagos.
- La pasarela valida con éxito la petición, descuenta el saldo y registra la transacción en la base de datos.
- En el momento de generar la respuesta 200 OK se corta la conexión o el balanceador la reinicia por timeout.
- El cliente
go-retryablehttpdetecta el error de redconnection reset by peer, rebobina el búfer del cuerpo de la petición y lo reenvía fielmente por segunda vez.
El resultado es predecible: si la API del otro lado no está preparada para rastrear duplicados, al usuario se le cobrará dos veces. Repetir «a ciegas» a nivel de transporte solo es seguro para métodos idempotentes según el estándar HTTP (GET, HEAD, PUT, DELETE). Para operaciones mutantes es obligatorio incluir una cabecera de aplicación Idempotency-Key con un UUID único de la operación:
// Generación de la cabecera de idempotencia antes del envío
req, err := retryablehttp.NewRequestWithContext(ctx, "POST", apiURL, bytes.NewReader(payload))
if err != nil {
return err
}
// El identificador único garantiza que la pasarela devuelva la respuesta en caché en lugar de duplicar
req.Header.Set("Idempotency-Key", orderUUID.String())
req.Header.Set("Content-Type", "application/json")
Política CheckRetry personalizada y jitter aleatorio
Otro matiz que suele olvidarse es el comportamiento del backoff. La función estándar de retardo DefaultBackoff en go-retryablehttp aumenta la pausa de forma exponencial, pero no le añade un jitter aleatorio (jitter). Si un microservicio externo parpadeó brevemente, cientos de instancias paralelas de tu aplicación lanzarán el reintento de forma sincronizada, creando el clásico problema de la «estampida» (thundering herd) y rematando al backend ya caído.
Una inicialización correcta del cliente exige sobrescribir la función de backoff con una adición aleatoria y controlar la cancelación del contexto:
package main
import (
"context"
"math/rand"
"net/http"
"time"
"github.com/hashicorp/go-retryablehttp"
)
func createSafeClient() *http.Client {
retryClient := retryablehttp.NewClient()
retryClient.RetryMax = 2 // 1 original + 2 reintentos
retryClient.RetryWaitMin = 100 * time.Millisecond
retryClient.RetryWaitMax = 2 * time.Second
// Añadimos un jitter aleatorio de hasta el 25% del intervalo
retryClient.Backoff = func(min, max time.Duration, attemptNum int, resp *http.Response) time.Duration {
mult := time.Duration(1 << uint(attemptNum))
sleep := min * mult
if sleep > max {
sleep = max
}
jitter := time.Duration(rand.Int63n(int64(sleep / 4)))
return sleep + jitter
}
// La cancelación del contexto detiene de inmediato el ciclo de reintentos
retryClient.CheckRetry = func(ctx context.Context, resp *http.Response, err error) (bool, error) {
if ctx.Err() != nil {
return false, ctx.Err()
}
return retryablehttp.DefaultRetryPolicy(ctx, resp, err)
}
return retryClient.StandardClient()
}
Recuerda que para interfaces no rebobinables io.Reader, la biblioteca lee todo el cuerpo de la petición en un slice de bytes en memoria RAM. Si a través de go-retryablehttp se envían archivos de cientos de megabytes, esto provocará un pico brusco de consumo de RAM y carga sobre el GC.
En resumen: la biblioteca go-retryablehttp elimina de maravilla la rutina de transporte, pero la responsabilidad arquitectónica de la idempotencia de los datos siempre recae en el desarrollador.

