Códigos de status HTTP

O código de status é o primeiro número da resposta de uma chamada HTTP e, muitas vezes, a única informação da resposta que chega ao log. O código informa como a camada que respondeu tratou a requisição, mas não identifica sozinho a causa de uma falha nem o resultado do negócio.

As cinco famílias

O primeiro algarismo do código indica a família da resposta:

• 1xx: respostas informativas, que não encerram a requisição, como o 100, que autoriza o cliente a continuar o envio do corpo.
• 2xx: a requisição foi recebida, compreendida e aceita.
• 3xx: o cliente precisa de outra ação para completar a requisição, como seguir para outro endereço.
• 4xx: o serviço percebeu um problema na requisição enviada pelo cliente.
• 5xx: o servidor não conseguiu atender uma requisição aparentemente válida.

Nessas definições, a palavra cliente designa o cliente HTTP, o programa que fez a chamada, e não a pessoa que abriu o atendimento. A resposta também pode vir de um intermediário, como um proxy ou um balanceador de carga, antes de a requisição chegar ao serviço de negócio.

Sucesso, 2xx

• 200: a requisição foi atendida, e o corpo traz o resultado conforme o método e o contrato.
• 201: um recurso foi criado, e o cabeçalho Location costuma indicar o endereço dele.
• 202: a requisição foi aceita para processamento, sem confirmação de conclusão.
• 204: a requisição foi atendida, e a resposta não tem corpo.

Um código 2xx confirma o atendimento da requisição, e não a aprovação do negócio. Uma resposta 200 pode trazer, no corpo, um benefício recusado, e uma resposta 201 pode registrar uma cobrança ainda pendente.

Redirecionamento, 3xx

• 301 e 308: o recurso mudou de endereço de forma permanente.
• 302 e 307: o recurso está em outro endereço de forma temporária.
• 304: a representação não mudou desde a versão que o cliente já tem, em uma consulta condicional.

Ao seguir um 301 ou um 302, alguns programas trocam o POST por GET e descartam o corpo, e a chamada chega ao endereço novo sem os dados. Os códigos 307 e 308 preservam o método e o corpo. Quando um fornecedor muda o endereço do serviço, a atualização do endereço na configuração evita depender de um redirecionamento.

Problemas na requisição, 4xx

• 400: o serviço não atende a requisição por um erro percebido nela, como um corpo malformado.
• 401: faltam credenciais de autenticação válidas.
• 403: o serviço recusou o atendimento, muitas vezes por falta de permissão.
• 404: o recurso não foi encontrado, ou o serviço preferiu não revelar se ele existe.
• 405: o método não é aceito para aquele recurso, e o cabeçalho Allow informa os métodos aceitos.
• 408: o servidor não recebeu a requisição completa dentro do prazo dele.
• 409: a requisição conflita com o estado atual do recurso, como em uma duplicidade prevista no contrato.
• 413: o conteúdo enviado é maior que o limite aceito pelo servidor.
• 415: o tipo de conteúdo declarado não é aceito.
• 422: o conteúdo foi compreendido, mas as instruções não puderam ser processadas, e muitas APIs usam esse código nas validações de negócio.
• 429: o cliente excedeu o limite de chamadas, e o cabeçalho Retry-After pode informar quanto tempo esperar.

Os códigos 400 e 422 não seguem uma regra única entre os fornecedores. No gateway de pagamento, uma data em formato inválido recebe o 400, e um valor total diferente da soma dos itens com o frete recebe o 422. Outro serviço pode usar o 400 nos dois casos, e a descrição do erro, no corpo, completa a leitura.

O código 408 também é diferente do tempo esgotado registrado pelo programa que chama. No 408, o servidor desistiu de esperar a requisição. No tempo esgotado do programa, o programa desistiu de esperar a resposta.

Falhas no servidor, 5xx

• 500: o servidor encontrou uma condição inesperada.
• 502: um intermediário recebeu uma resposta inválida do servidor que ele acessa.
• 503: o serviço está indisponível no momento, por sobrecarga ou manutenção, e pode informar o Retry-After.
• 504: um intermediário esgotou o tempo de espera pela resposta do servidor que ele acessa.

Esses códigos indicam a camada que respondeu, e não quem deve corrigir o problema. Um 502 ou um 504 vem do intermediário, enquanto o serviço de negócio pode estar processando ou já ter processado a operação. Um 5xx também pode acontecer depois de uma cobrança criada, e por isso a situação da cobrança é consultada antes de qualquer repetição.

Código recuperável e repetição

Os códigos 429 e 503 indicam situações passageiras e podem trazer, no cabeçalho Retry-After, o tempo de espera sugerido. Essa indicação não autoriza repetir uma operação de alteração sem conhecer o resultado da tentativa anterior e a proteção do contrato contra duplicidade.

Quando a integração prevê repetição, as tentativas seguem pausas e um limite de quantidade e de tempo total. Repetições rápidas e sem limite aumentam a sobrecarga do serviço. O registro do atendimento guarda o código de cada tentativa, e não só o último sucesso ou o último erro.