Calling other APIs safely with the HTTP client

Why a careful client matters

Backends constantly call other services: a payment gateway, an SMS provider, a weather API. If one of them hangs and your client waits forever, your own server slowly runs out of goroutines and connections, and then it hangs too. Most production outages involving Go HTTP clients come from a few simple mistakes covered here.

The safe pattern

var client = &http.Client{Timeout: 10 * time.Second} // create once, reuse

func getRates(ctx context.Context) ([]byte, error) {
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/rates", nil)
	if err != nil {
		return nil, err
	}
	resp, err := client.Do(req)
	if err != nil {
		return nil, fmt.Errorf("call rates api: %w", err) // network error, timeout...
	}
	defer resp.Body.Close()

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("rates api: unexpected status %s", resp.Status)
	}
	return io.ReadAll(io.LimitReader(resp.Body, 1<<20)) // read at most 1 MB
}

The five rules, explained

1. Set a Timeout. http.Get, http.Post and http.DefaultClient have NO timeout. Timeout covers the whole exchange: connecting, sending, and reading the body.
2. Reuse one client. An http.Client keeps a pool of open connections (keep-alive) in its Transport. Creating a new client per request throws that away and can exhaust ports under load. A client is safe to share between goroutines.
3. Close the body. If you forget resp.Body.Close(), the connection cannot go back to the pool and you leak resources. Reading the body to the end also helps the connection to be reused.
4. Check the status code. err is only non-nil for problems like DNS failure, refused connection or timeout. A 404 or 500 response comes back with err == nil.
5. Limit what you read. A broken or hostile server could send gigabytes; io.LimitReader caps it.

Sending JSON

type Payout struct {
	Account string `json:"account"`
	Paise   int64  `json:"amount_paise"`
}

body, err := json.Marshal(Payout{Account: "XXXX1234", Paise: 250000})
if err != nil {
	return err
}
req, err := http.NewRequestWithContext(ctx, http.MethodPost, "https://api.example.com/payouts", bytes.NewReader(body))
if err != nil {
	return err
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Idempotency-Key", orderID) // if the provider supports it

resp, err := client.Do(req)

Decoding a JSON response

var out struct {
	Status string `json:"status"`
	TxnID  string `json:"txn_id"`
}
if err := json.NewDecoder(resp.Body).Decode(&out); err != nil {
	return fmt.Errorf("decode payout response: %w", err)
}

Retries, carefully

Networks fail now and then, so clients often retry. Retry only when it is safe: GET requests, or POSTs that the provider makes idempotent (the same Idempotency-Key never charges twice). Wait longer after each try (exponential backoff, for example 200 ms, 400 ms, 800 ms) and stop after a few attempts or when the context is done. Never blindly retry a payment.