What are the rules for writing HTTP responses correctly in Go handlers?

The http.ResponseWriter interface has ordering rules that are easy to violate, leading to subtle bugs where headers are silently lost or the response is malformed.

// http.ResponseWriter interface:
// type ResponseWriter interface {
//     Header() http.Header    // returns the header map (modify before WriteHeader)
//     WriteHeader(statusCode int) // sets status; can only be called once
//     Write([]byte) (int, error)  // writes body; implicitly calls WriteHeader(200)
// }

// CORRECT ordering:
func goodHandler(w http.ResponseWriter, r *http.Request) {
    // 1. Set headers first
    w.Header().Set("Content-Type", "application/json")
    w.Header().Set("X-Request-ID", "abc-123")

    // 2. Set status code
    w.WriteHeader(http.StatusCreated) // 201

    // 3. Write body
    json.NewEncoder(w).Encode(map[string]string{"status": "created"})
}

// WRONG: setting headers after WriteHeader — silently ignored
func badHandler(w http.ResponseWriter, r *http.Request) {
    w.WriteHeader(http.StatusOK)
    w.Header().Set("Content-Type", "application/json") // TOO LATE — ignored!
    w.Write([]byte(`{"ok":true}`))
}

// WRONG: calling Write before setting Content-Type
// Write triggers an implicit WriteHeader(200) — headers lock

// Helper: structured JSON response
func writeJSON(w http.ResponseWriter, status int, v any) {
    w.Header().Set("Content-Type", "application/json")
    w.WriteHeader(status)
    if err := json.NewEncoder(w).Encode(v); err != nil {
        log.Printf("writeJSON: %v", err)
    }
}

// IMPORTANT: returning from a handler does NOT automatically
// stop a response from being written. Use explicit return after error:
func handler(w http.ResponseWriter, r *http.Request) {
    if err := process(r); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return // MUST return — otherwise code below also runs
    }
    writeJSON(w, http.StatusOK, map[string]string{"ok": "true"})
}

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.