APIs com Golang - 2026

8 - Compreendendo e Configurando Status Code HTTP

Quando desenvolvemos uma API, não basta apenas devolver os dados corretos no formato JSON; também precisamos informar ao cliente (seja um navegador, aplicativo mobile ou outro servidor) se a requisição foi bem-sucedida ou se ocorreu algum erro. Fazemos isso através dos Status Codes HTTP (Códigos de Status).

O que são Status Code?

Os códigos de status HTTP são números de três dígitos organizados em cinco categorias principais. Eles servem como uma resposta rápida e padronizada do servidor sobre o resultado de um pedido. Por exemplo, quando você acessa uma página que não existe, o famoso erro 404 Not Found é um código de status.

Tabela de Status Code HTTP

Abaixo estão listados os códigos de status definidos pelo protocolo HTTP, separados por suas respectivas famílias:

Implementando o Status Code em Go

No Go, nós controlamos o status da resposta usando o método w.WriteHeader(). O pacote net/http nos fornece constantes amigáveis para não precisarmos decorar os números dos códigos de status. Veja abaixo a atualização do nosso arquivo main.go:

// Pacote principal da aplicação
package main

// Importações
import (
	"encoding/json"
	"fmt"
	"net/http"
)

// Função para retornar um Hello World!
func helloWorld(w http.ResponseWriter, r *http.Request) {

	// 1. Definir o cabeçalho informando que a resposta é um JSON
	w.Header().Set("Content-Type", "application/json")

	// 2. Definir o Status Code Explicitamente
	// http.StatusCreated equivale ao código numérico 201
	w.WriteHeader(http.StatusCreated)

	// 3. Criar JSON mensagem
	mensagem := map[string]string{
		"mensagem": "Hello World!",
	}

	// 4. Converter o map para JSON e retornar
	json.NewEncoder(w).Encode(mensagem)
}

// Função principal
func main() {

	// Rotas
	http.HandleFunc("GET /", helloWorld)

	// Retornar o funcionamento do servidor
	fmt.Println("Servidor em execução no endereço: http://localhost:8080")

	// Configurar servidor
	http.ListenAndServe(":8080", nil)

}

Atenção: A função w.WriteHeader() deve ser sempre chamada antes do json.NewEncoder(w).Encode(). Se você tentar alterar o status code depois que os dados já começaram a ser enviados para o cliente, o Go emitirá um aviso no terminal e manterá o status padrão 200 (OK).