← Voltar para o blog

Cliente HTTP em Go: Timeout, Transport e Retry

Monte um cliente HTTP em Go para produção: timeouts, Transport, keep-alive, retry com backoff, context, testes com httptest e quando usar resty.

Resposta rápida: um cliente HTTP em Go de produção não usa http.DefaultClient. Você cria um *http.Client reutilizável, define Timeout, configura o http.Transport (dial, TLS, response headers, keep-alive, idle conns), propaga context.Context, faz retry só em falhas transitórias e operações idempotentes, e observa erros com logs/métricas. Isso protege goroutines, conexões e latência do seu serviço quando a API externa trava. Combine com circuit breaker, httptrace e context com timeout — não substitua um pelo outro.

Este guia monta o client do zero: defaults perigosos, Transport, retries, headers, testes com httptest, comparação com resty e um checklist de produção. Se você está do outro lado da conexão (servidor), veja middleware em Go, Chi Router e o tutorial de API REST.

Por que DefaultClient quebra em produção

http.DefaultClient parece conveniente:

resp, err := http.Get("https://api.exemplo.com/v1/status")

O problema é estrutural:

ComportamentoDefaultClientClient de produção
Timeout total0 (infinito)Explícito (ex.: 10s)
TransportGlobal compartilhadoPróprio, afinado
CancelamentoSó se você passar contextSempre via context
RetryNenhumControlado e idempotente
ObservabilidadeManual e fácil de esquecerEncapsulada no client

Sem timeout, um fornecedor lento prende a goroutine do request, satura o pool de conexões e eleva a latência de todo o serviço — mesmo endpoints que não chamam essa API. Em backends brasileiros que falam com antifraude, PIX, ERP, CRM e gateways, isso aparece como “o pod congelou” sem panic.

A regra prática: um *http.Client por processo (ou por dependência), criado no bootstrap, injetado nos pacotes que falam com o mundo externo.

Cliente mínimo seguro

package payments

import (
	"net"
	"net/http"
	"time"
)

func NewHTTPClient() *http.Client {
	transport := &http.Transport{
		Proxy: http.ProxyFromEnvironment,
		DialContext: (&net.Dialer{
			Timeout:   5 * time.Second,
			KeepAlive: 30 * time.Second,
		}).DialContext,
		ForceAttemptHTTP2:     true,
		MaxIdleConns:          100,
		MaxIdleConnsPerHost:   20,
		MaxConnsPerHost:       50,
		IdleConnTimeout:       90 * time.Second,
		TLSHandshakeTimeout:   5 * time.Second,
		ExpectContinueTimeout: 1 * time.Second,
		ResponseHeaderTimeout: 10 * time.Second,
	}

	return &http.Client{
		Timeout:   15 * time.Second,
		Transport: transport,
	}
}

O que cada peça controla:

  • Client.Timeout: teto absoluto da chamada (dial + TLS + headers + body).
  • DialContext: quanto tempo esperar para abrir TCP.
  • TLSHandshakeTimeout: handshake TLS lento não prende o worker sem limite.
  • ResponseHeaderTimeout: o servidor aceitou a conexão mas não devolveu headers a tempo.
  • MaxIdleConns / MaxIdleConnsPerHost: reuso de keep-alive sem abrir socket novo a cada request.
  • MaxConnsPerHost: teto duro contra stampede em um único host.

Client.Timeout sozinho não substitui os timeouts do Transport: ele cancela a chamada inteira, mas o Transport deixa falhas parciais mais previsíveis e mensagens de erro mais claras.

Context por request

O client compartilhado define o teto. O context do request de entrada (ou do job) define o deadline real:

package payments

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"time"
)

type Client struct {
	baseURL string
	http    *http.Client
}

func (c *Client) FetchStatus(ctx context.Context, id string) ([]byte, error) {
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/v1/charges/"+id, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("User-Agent", "golang-com-br-payments/1.0")

	resp, err := c.http.Do(req)
	if err != nil {
		return nil, fmt.Errorf("payments fetch: %w", err)
	}
	defer resp.Body.Close()

	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20)) // 1 MiB
	if err != nil {
		return nil, fmt.Errorf("payments read body: %w", err)
	}
	if resp.StatusCode >= 400 {
		return nil, fmt.Errorf("payments status %d: %s", resp.StatusCode, body)
	}
	return body, nil
}

Pontos que evitam incidentes:

  1. Sempre NewRequestWithContext, nunca http.NewRequest + Do sem context.
  2. Limite o tamanho do body (LimitReader) — resposta gigante também é DoS.
  3. Feche o body sempre (defer resp.Body.Close()), mesmo em erro de status.
  4. Encapsule a URL base e headers comuns no tipo Client, não no handler.

Para cancelamento em cascata e timeouts encadeados, o guia de context em Go é o complemento direto.

Retry com backoff — só quando é seguro

Retry mal feito piora o incidente: multiplica carga no fornecedor e duplica efeitos colaterais. A política segura:

SituaçãoRetry?
Timeout de rede / conexão resetadaSim, com limite
HTTP 408, 429, 502, 503, 504Sim, se a operação for idempotente
HTTP 400, 401, 403, 404, 422Não
POST de criação sem chave de idempotênciaNão
GET, PUT idempotente, DELETE idempotenteSim, com cuidado
Body parcialmente lido / erro depois do commit remotoNão adivinhe — use idempotency-key

Esboço mínimo sem biblioteca:

package payments

import (
	"context"
	"errors"
	"io"
	"math/rand"
	"net"
	"net/http"
	"strconv"
	"time"
)

func (c *Client) doWithRetry(ctx context.Context, req *http.Request, maxAttempts int) (*http.Response, error) {
	var lastErr error
	for attempt := 1; attempt <= maxAttempts; attempt++ {
		// Body precisa ser recriável: use GetBody ou buffer.
		if attempt > 1 && req.GetBody != nil {
			body, err := req.GetBody()
			if err != nil {
				return nil, err
			}
			req.Body = body
		}

		resp, err := c.http.Do(req)
		if err == nil && !retryableStatus(resp.StatusCode) {
			return resp, nil
		}

		if err == nil {
			io.Copy(io.Discard, resp.Body)
			resp.Body.Close()
			lastErr = errors.New("retryable status " + strconv.Itoa(resp.StatusCode))
			if ra := resp.Header.Get("Retry-After"); ra != "" {
				if sec, parseErr := strconv.Atoi(ra); parseErr == nil {
					if err := sleep(ctx, time.Duration(sec)*time.Second); err != nil {
						return nil, err
					}
					continue
				}
			}
		} else {
			lastErr = err
			if !retryableNetErr(err) {
				return nil, err
			}
		}

		if attempt == maxAttempts {
			break
		}
		backoff := time.Duration(1<<uint(attempt-1)) * 100 * time.Millisecond
		jitter := time.Duration(rand.Intn(100)) * time.Millisecond
		if err := sleep(ctx, backoff+jitter); err != nil {
			return nil, err
		}
	}
	return nil, lastErr
}

func retryableStatus(code int) bool {
	switch code {
	case 408, 429, 500, 502, 503, 504:
		return true
	default:
		return false
	}
}

func retryableNetErr(err error) bool {
	var netErr net.Error
	return errors.As(err, &netErr) && netErr.Timeout()
}

func sleep(ctx context.Context, d time.Duration) error {
	t := time.NewTimer(d)
	defer t.Stop()
	select {
	case <-ctx.Done():
		return ctx.Err()
	case <-t.C:
		return nil
	}
}

Na prática, muitas equipes preferem uma lib pequena de backoff ou o retry embutido de um wrapper interno. O importante é a política, não a lib. Para filas e workers, o padrão completo de idempotência, retry e DLQ evita duplicar efeitos financeiros. Quando o fornecedor fica ruim de verdade, circuit breaker corta o tráfego — retry sozinho não basta.

Transport: conexões, HTTP/2 e armadilhas

Reutilize o mesmo Transport (via o mesmo *http.Client). Criar http.Client{Transport: &http.Transport{}} por request descarta keep-alive e explode o número de sockets.

Cuidados frequentes:

  1. MaxIdleConnsPerHost baixo demais — sob carga, Go abre conexões novas sem reuso; suba para 10–64 conforme o host.
  2. Esquecer IdleConnTimeout — conexões mortas ficam no pool e falham no próximo uso.
  3. Proxy corporativo — ProxyFromEnvironment respeita HTTP_PROXY/HTTPS_PROXY; em Kubernetes isso às vezes surpreende.
  4. HTTP/2 — ForceAttemptHTTP2: true é o padrão moderno; se o fornecedor tiver bug de multiplexação, teste com HTTP/1.1 só nesse host.
  5. TLS custom — mTLS e root CAs vão em transport.TLSClientConfig; não misture clients com políticas de certificado diferentes no mesmo Transport se os hosts exigem configs distintas.
  6. Redirects — Client.CheckRedirect limita saltos; para APIs autenticadas, valide se o Authorization não vaza para outro host.

Para inspecionar DNS, connect, TLS e TTFB em runtime, use httptrace no client de debug — não deixe trace ligado em todo request de produção sem amostragem.

Headers, autenticação e corpos

Padronize no wrapper:

  • Accept e Content-Type explícitos
  • User-Agent com nome do serviço e versão (ajuda suporte do fornecedor)
  • Authorization via RoundTripper ou middleware interno — não espalhe token em cada handler
  • Idempotency-Key em POST de pagamento / criação
  • Correlation / trace id alinhado ao OpenTelemetry

Para JSON:

req.Header.Set("Content-Type", "application/json")

Encode para um bytes.Buffer, defina req.ContentLength e, se houver retry, configure req.GetBody para reabrir o buffer. Sem GetBody, a segunda tentativa envia body vazio.

resty vs net/http

Critérionet/httpresty
DependênciaBiblioteca padrãoExterna
Controle fino de TransportTotalBom, mas atrás da API fluente
Retry / middlewareVocê montaJá vem
TestabilidadeExcelente com httptestBoa
Ideal quandoClient estável, política própriaPrototipar rápido / muitos endpoints

Recomendação para APIs de produção no Brasil: comece com net/http encapsulado. Se o pacote interno crescer demais só por boilerplate, avalie resty ou codegen OpenAPI (oapi-codegen). Evite misturar três clients diferentes no mesmo serviço sem motivo.

Testes com httptest

package payments_test

import (
	"context"
	"net/http"
	"net/http/httptest"
	"testing"
	"time"
)

func TestFetchStatusTimeout(t *testing.T) {
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		time.Sleep(200 * time.Millisecond)
		w.WriteHeader(http.StatusOK)
	}))
	t.Cleanup(srv.Close)

	client := &http.Client{Timeout: 50 * time.Millisecond}
	ctx := context.Background()
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, srv.URL, nil)
	if err != nil {
		t.Fatal(err)
	}
	_, err = client.Do(req)
	if err == nil {
		t.Fatal("esperava timeout")
	}
}

Cubra também:

  • status 429 com Retry-After
  • body maior que o limite
  • cancelamento via context.WithCancel
  • retry que eventualmente sucede
  • erro 4xx sem retry

O guia de mocks e httptest detalha a fronteira entre fake HTTP e mock de interface.

Observabilidade mínima

Sem telemetria, timeout vira “está lento” no Slack. Instrumente por dependência:

  • contador de requests por host + status
  • histograma de latência (dial vs total, se possível)
  • contador de retries e de circuit open
  • log estruturado com slog (guia de slog) incluindo url_host, method, attempt, err

Não logue Authorization, cookies nem bodies com PII. Em pagamentos, trate payloads como sensíveis por padrão — o panorama de Go em fintechs reforça idempotência e auditoria além do client.

Checklist de produção

  • Nenhum uso de http.DefaultClient / http.Get / http.Post no caminho quente
  • *http.Client criado uma vez, com Timeout > 0
  • Transport próprio com dial, TLS, response header e idle conns
  • NewRequestWithContext em todas as chamadas
  • Body limitado na leitura; Close garantido
  • Retry só para erros transitórios + operações idempotentes
  • Backoff com jitter e respeito a Retry-After
  • Circuit breaker nas dependências críticas
  • User-Agent e correlation id padrão
  • Testes httptest para timeout, 429 e cancelamento
  • Métricas e logs sem vazar segredo

Perguntas frequentes

Devo usar http.DefaultClient em produção?

Não. Ele não tem timeout e compartilha Transport global. Crie um *http.Client com Timeout e Transport afinado, e reutilize no processo. DefaultClient é aceitável em scripts one-shot, não em API ou worker.

Qual timeout configurar no http.Client?

Use um teto no Client (por exemplo 5–15s conforme o SLA) e timeouts parciais no Transport (DialContext, TLSHandshakeTimeout, ResponseHeaderTimeout). O context do request pode apertar ainda mais o deadline. Timeout zero = espera infinita.

Como fazer retry seguro em cliente HTTP Go?

Repita só falhas transitórias (timeout de rede, 429, 5xx) em operações idempotentes. Exija idempotency-key para POST de efeito colateral. Backoff exponencial com jitter, limite de tentativas, Retry-After e cancelamento via context. Some circuit breaker quando o fornecedor cai de verdade.

Preciso de resty ou o net/http basta?

net/http basta na maioria dos clients de produção. resty reduz boilerplate se o time quer API fluente e retry pronto. Se você já tem um pacote interno claro, a dependência extra raramente se justifica.

Como testar um cliente HTTP em Go?

Suba httptest.NewServer, simule latência, 429, body enorme e cancelamento de context. Reserve chamadas reais para testes de contrato em sandbox. Evite mockar Do com framework se um servidor fake cobre o comportamento.

Conclusão

Cliente HTTP em Go é infraestrutura, não detalhe de sintaxe. Timeout, Transport, context, retry idempotente e observabilidade separam um serviço que sobrevive a um fornecedor instável de um serviço que cai junto. Encapsule o client, teste com httptest e combine com circuit breaker — em vez de espalhar http.Get pelos handlers.

Para seguir: circuit breaker, httptrace, context e cancelamento, idempotência e DLQ, rate limiting e OpenTelemetry. Se a meta é backend no mercado brasileiro, acompanhe as vagas Go e o guia de salários.

Referências oficiais