HTTP na prática: métodos, status e cabeçalhos que todo dev usa

Todo aplicativo web, por mais sofisticado que pareça, conversa com o servidor através de um protocolo surpreendentemente simples de entender: o HTTP. Cada clique, cada formulário enviado, cada imagem carregada é, no fundo, uma requisição de texto que sai do navegador, atravessa a rede e volta como uma resposta também de texto. A elegância do HTTP está em ser legível: se você abrir a aba de rede das ferramentas do desenvolvedor, verá exatamente o que foi pedido, com quais métodos, e o que voltou, com quais códigos. Dominar essa conversa é pré-requisito para depurar qualquer coisa que envolva front e back trocando dados.

O problema é que muita gente trata o HTTP como uma caixa-preta que a biblioteca de requisições resolve sozinha. Chama-se uma função, os dados chegam, e ninguém para para pensar por que aquele método foi usado, o que aquele status realmente significa ou qual cabeçalho controla o comportamento observado. Quando algo dá errado — uma requisição que devia funcionar retorna erro, um cache que não invalida, um dado que chega truncado — a falta desse entendimento vira horas perdidas.

Este artigo percorre as três dimensões do HTTP que aparecem no dia a dia: os métodos, que declaram a intenção da requisição; os códigos de status, que resumem o resultado; e os cabeçalhos, que carregam os metadados que fazem o protocolo funcionar de verdade. A ideia é sair da decoreba e entender a mecânica, para que cada escolha faça sentido.

Anatomia de uma requisição#

Antes dos detalhes, vale fixar o formato. Uma requisição HTTP tem uma linha inicial com o método e o caminho, um bloco de cabeçalhos no formato nome e valor, uma linha em branco, e opcionalmente um corpo. A resposta segue a mesma estrutura: uma linha com o código de status, os cabeçalhos, a linha em branco e o corpo. Tudo isso é texto estruturado, o que significa que qualquer ferramenta consegue inspecionar e reproduzir uma requisição.

O ponto conceitual importante é que o HTTP não guarda estado entre requisições. Cada requisição é independente e o servidor, em princípio, não lembra da anterior. Tudo que precisa persistir entre uma requisição e outra — quem é o usuário, o que está no carrinho — precisa ser reenviado ou referenciado explicitamente, geralmente por cookies ou tokens carregados nos cabeçalhos. Essa ausência de memória é o que torna o HTTP escalável e, ao mesmo tempo, o que obriga a inventar mecanismos de sessão por cima dele.

Os métodos e o que eles declaram#

O método é a primeira palavra da requisição e declara a intenção da operação. Ele não é uma mera formalidade: servidores, caches e intermediários se comportam de formas diferentes conforme o método, e usar o método certo faz o sistema inteiro se comportar melhor.

• GET pede um recurso sem causar efeitos colaterais. É a operação de leitura por excelência, e o servidor deve poder respondê-la quantas vezes for, sempre sem mudar nada. Como é seguro, o resultado de um GET pode ser cacheado e a URL pode ser guardada nos favoritos.
• POST envia dados para o servidor processar, tipicamente criando algo novo. Não é seguro nem idempotente: repetir um POST pode criar dois registros. É por isso que recarregar uma página após enviar um formulário faz o navegador perguntar se você quer reenviar.
• PUT substitui um recurso inteiro por uma nova versão. Sua característica marcante é a idempotência: enviar o mesmo PUT uma ou dez vezes deixa o servidor no mesmo estado final.
• PATCH aplica uma modificação parcial, mudando apenas alguns campos em vez de substituir tudo.
• DELETE remove um recurso, e também é idempotente: apagar algo já apagado leva ao mesmo estado.

Segurança e idempotência na prática#

Esses dois conceitos — segurança e idempotência — parecem teóricos, mas têm consequências concretas. Um método seguro pode ser repetido por um crawler ou por um pré-carregador do navegador sem risco, então nunca coloque uma ação destrutiva atrás de um GET: um link que apaga algo será acionado por qualquer robô que visitar a página. A idempotência, por sua vez, é o que permite que clientes tentem de novo com segurança quando a rede falha. Se uma requisição idempotente não recebe resposta, o cliente pode reenviá-la sem medo de duplicar o efeito. Já um POST sem proteção precisa de mecanismos extras, como uma chave de idempotência, para tolerar retentativas.

Os códigos de status e o que eles contam#

A resposta traz um código de três dígitos que resume o desfecho. A primeira digito define a classe, e conhecer as classes já orienta metade da depuração.

A classe 2xx significa sucesso. O 200 OK é o caso geral; o 201 Created confirma que um recurso novo foi criado, tipicamente em resposta a um POST; o 204 No Content diz que deu certo mas não há corpo para devolver, comum em operações de exclusão.

A classe 3xx trata de redirecionamento. O 301 Moved Permanently diz que o recurso mudou de endereço para sempre, e mecanismos de busca atualizam seus índices por causa dele; o 302 Found sinaliza um desvio temporário; o 304 Not Modified é uma resposta de cache, dizendo ao navegador que a versão que ele já tem continua válida e pode ser reutilizada sem baixar de novo.

A classe 4xx aponta erro do cliente — a requisição chegou, mas tinha algo errado. O 400 Bad Request indica requisição malformada; o 401 Unauthorized diz que falta autenticação; o 403 Forbidden diz que o cliente está autenticado mas não tem permissão; o 404 Not Found é o clássico recurso inexistente; o 409 Conflict sinaliza um choque com o estado atual, como tentar criar algo que já existe; o 422 costuma indicar dados semanticamente inválidos; e o 429 Too Many Requests avisa que o cliente excedeu um limite de taxa.

A classe 5xx aponta erro do servidor — a requisição estava certa, mas algo quebrou do outro lado. O 500 Internal Server Error é o erro genérico; o 502 Bad Gateway e o 503 Service Unavailable costumam aparecer quando um serviço intermediário ou de retaguarda está fora do ar.

A distinção que mais confunde: 401 versus 403#

Vale gastar uma linha na diferença entre 401 e 403, porque ela é fonte perene de confusão. O 401 significa "não sei quem você é" — falta credencial válida, e o caminho é fazer login. O 403 significa "sei quem você é, mas você não pode fazer isso" — a credencial é válida, mas a autorização não alcança aquele recurso. Enviar 403 quando devia ser 401, ou vice-versa, confunde o cliente sobre o que fazer a seguir, e também tem implicações de segurança, já que às vezes é preferível responder 404 para não revelar que um recurso existe.

Os cabeçalhos que fazem o trabalho pesado#

Se os métodos declaram a intenção e os status resumem o resultado, os cabeçalhos são onde o protocolo realmente ganha vida. Eles carregam metadados que controlam formato, cache, autenticação, negociação de conteúdo e muito mais.

O cabeçalho Content-Type declara o formato do corpo — se é JSON, se é HTML, se é um formulário codificado, se é uma imagem. O servidor e o cliente usam esse valor para saber como interpretar os bytes que recebem. Enviar dados JSON sem declarar o tipo correto é uma das causas mais comuns de uma API rejeitar uma requisição que "parecia certa".

O cabeçalho Accept faz o caminho inverso: o cliente diz quais formatos ele consegue entender, e o servidor escolhe o melhor entre eles. Esse é o mecanismo da negociação de conteúdo, que permite o mesmo endereço servir JSON para um programa e HTML para um navegador.

O cabeçalho Authorization transporta a credencial — tipicamente um token — que autentica a requisição. É por meio dele que o servidor sabe quem está fazendo o pedido, já que o HTTP não guarda estado. E como esse valor é sensível, ele só deve trafegar sobre conexões cifradas.

Cabeçalhos de cache e de conteúdo#

Um grupo especialmente importante controla o cache. O Cache-Control diz por quanto tempo e sob quais condições uma resposta pode ser reutilizada; o ETag fornece uma impressão digital da versão do recurso, que o cliente reenvia para perguntar se algo mudou; o Last-Modified cumpre papel parecido baseado em data. Esses cabeçalhos são o que permite ao navegador evitar baixar de novo o que ele já tem, e o que faz o servidor responder 304 em vez de reenviar o corpo inteiro.

Outro grupo trata do tamanho e da forma do corpo. O Content-Length informa quantos bytes vêm; o Content-Encoding diz se o corpo veio comprimido, o que reduz o tráfego; o Transfer-Encoding com valor de fragmentação permite enviar a resposta em pedaços sem saber o tamanho total de antemão, útil para conteúdo gerado sob demanda.

Negociação, compressão e conexões#

Por trás dos cabeçalhos individuais existe um princípio: o HTTP é um protocolo de negociação entre duas partes que não se conhecem. O cliente anuncia o que aceita, o servidor responde com o que decidiu, e ambos se ajustam. A compressão é um exemplo perfeito: o navegador manda no cabeçalho de codificação aceita que sabe descomprimir determinados formatos; o servidor comprime a resposta e marca no Content-Encoding qual foi usado; o navegador descomprime antes de entregar ao código. Tudo isso acontece de forma transparente, mas entender que existe uma negociação explica por que às vezes a compressão não acontece — basta um dos lados não anunciar suporte.

As versões mais novas do protocolo trouxeram ganhos que valem conhecer conceitualmente. Elas permitem enviar várias requisições em paralelo sobre a mesma conexão, sem esperar uma terminar para começar a próxima, e comprimem os próprios cabeçalhos, que em páginas modernas se repetem muito de requisição para requisição. O efeito prático é que abrir muitas conexões deixou de ser necessário, e otimizações antigas baseadas em juntar arquivos para reduzir número de requisições perderam parte da importância.

Levando para o dia a dia#

O valor de entender HTTP não está em decorar tabelas de status, e sim em ganhar a capacidade de ler o que está acontecendo. Quando uma requisição falha, o método diz o que o cliente pretendia, o status resume o resultado e os cabeçalhos contam os detalhes. Um 415 revela que o Content-Type estava errado; um 304 explica por que a resposta veio vazia mas a página funcionou; um 429 mostra que o cliente bateu num limite; um 401 versus 403 diz se o problema é de login ou de permissão.

Essa fluência transforma a aba de rede de um amontoado de linhas coloridas em uma narrativa que você lê. Você deixa de adivinhar e passa a diagnosticar. E, do outro lado, quando é você quem constrói a API, escolher o método correto, devolver o status honesto e usar os cabeçalhos apropriados faz o seu serviço se comportar bem com navegadores, caches, proxies e qualquer cliente que fale HTTP — que é, na web, todo mundo. Dominar esse protocolo não é um luxo de especialista; é a alfabetização básica de quem constrói para a rede.