Códigos de status de sucesso 2xx

O que a família 2xx cobre

Sucesso não é uma condição única. Um navegador buscando uma página, um formulário postando um registro novo, um job em segundo plano aceitando trabalho para depois e um player de vídeo pedindo os bytes de 5.000.000 a 6.000.000 são todos bem-sucedidos, mas precisam de respostas diferentes. É isso que os códigos 2xx codificam. A RFC 9110 define de 200 a 206; um punhado de outros vem de extensões como o WebDAV.

Para o tráfego web do dia a dia, a esmagadora maioria das respostas bem-sucedidas são 200s simples. O resto importa principalmente para clientes de API, caminhos de upload e entrega de mídia.

Os códigos 2xx e quando cada um aparece

• 200 OK. O sucesso padrão. Para um GET, o corpo é o recurso solicitado; para um POST, é o resultado da ação. É isso que uma página saudável devolve.
• 201 Created. A requisição criou um recurso novo. Uma API bem-comportada devolve 201 com um cabeçalho Location apontando para a coisa que acabou de criar. Você vê isso em logs de API, raramente em um navegador.
• 202 Accepted. A requisição foi aceita para processamento mas ainda não terminou. Usado para trabalho assíncrono como uma importação em massa ou um relatório que vai ser gerado em segundo plano. Um 202 é uma promessa, não um resultado, então o cliente normalmente precisa consultar uma URL de status.
• 203 Non-Authoritative Information. Sucesso, mas um proxy ou intermediário transformador modificou a resposta no caminho. Incomum em sites modernos.
• 204 No Content. Sucesso deliberadamente sem corpo. Típico de um DELETE, um PUT que salvou sem precisar ecoar nada de volta, ou um endpoint de salvamento automático. O navegador permanece na página atual.
• 205 Reset Content. Sucesso, e o cliente deveria resetar o formulário ou a visão de documento que enviou a requisição. Raramente usado na prática.
• 206 Partial Content. O servidor está devolvendo só o intervalo de bytes que o cliente pediu com um cabeçalho Range. É assim que busca em vídeo, downloads retomáveis e transferências de arquivo grande funcionam, então o 206 é normal e esperado em endpoints de mídia.
• 207 Multi-Status e 208 Already Reported vêm do WebDAV, onde uma requisição pode agir sobre vários recursos e precisa reportar um resultado por recurso. 226 IM Used vem da extensão de codificação delta e é muito raramente implantado.

Por que um 200 não prova que a página está saudável

Um código de status descreve o resultado da transação HTTP, não a correção do que voltou. Uma página personalizada de "estamos fora do ar para manutenção" é servida com um 200. Assim como uma página de erro de aplicação, quando o framework captura a exceção e renderiza um pedido de desculpas amigável pelo template normal com o status padrão dele. Uma página renderizada no cliente cuja chamada de API falhou devolve 200 para a casca vazia em torno do conteúdo ausente, e um soft 404 devolve 200 para uma mensagem de "página não encontrada", o que também confunde os buscadores.

Em cada um desses casos, uma verificação de código de status reporta sucesso enquanto os seus visitantes veem um site quebrado. A correção é uma verificação de conteúdo: faça uma asserção de que uma string conhecida está presente no corpo da resposta, ou que uma string de erro conhecida está ausente, além de verificar o código.

Como verificar o que uma URL realmente devolve

1. Peça só os cabeçalhos e leia a linha de status:

   curl -sI https://example.com/ | head -n 1

2. Se for um 200, busque o corpo também e confirme que contém o que deveria. Procure por uma string que só aparece em uma página funcionando, como um título ou um marcador de rodapé.
3. Para um endpoint de API, verifique se o código bate com a semântica: uma criação deveria ser 201 com um Location, uma exclusão deveria ser 204, e um job de longa duração deveria ser 202 com uma URL de status.
4. Para mídia, confirme que o servidor anuncia Accept-Ranges: bytes e responde a uma requisição com intervalo com 206. Se ele responder 200 a uma requisição com intervalo, a busca vai ser lenta porque o arquivo inteiro é reenviado.
5. Repita a verificação a partir de uma rede diferente. Uma resposta que é 200 para você e um erro em outro lugar aponta para DNS, CDN ou roteamento geográfico em vez da aplicação.

Verificando o corpo, não só o código

Uma verificação de código de status vai reportar um site verde que está servindo uma página de erro, então combine com uma asserção de conteúdo na mesma requisição. A HostTracker monitora sites desde 2004 e oferece 13 tipos de monitor, então uma URL pode ser observada pelo código de status, por uma palavra-chave na resposta e pelo tempo de resposta ao mesmo tempo. Rode uma URL pela ferramenta de verificação HTTP para ver o código e os cabeçalhos que ela devolve agora, depois leia o que um 200 OK realmente significa e os códigos de erro de servidor 5xx para as falhas que um 200 pode mascarar.