Definição de 428 e quando ele aparece

O código HTTP 428 — Precondition Required — indica que o servidor não vai processar a solicitação porque considera que estão faltando precondições (condições condicionais) necessárias para continuar. Em termos práticos, o servidor espera que o cliente forneça evidências ou critérios de estado (por exemplo, “só aceite se o recurso ainda tiver esta versão”).

Esse comportamento é comum quando o servidor quer evitar que uma operação seja executada em um contexto desatualizado, reduzindo a chance de sobrescrita indevida ou inconsistências. Na prática, o 428 funciona como um sinal de “você precisa incluir as condições corretas para que eu possa prosseguir”.

Funcionamento: precondições e cabeçalhos condicionais

A ideia central do 428 é que a requisição precisa chegar com informações adicionais que o servidor use para verificar o estado do recurso ou o direito de executar a ação.

Em muitos cenários, as precondições são expressas por cabeçalhos condicionais. Um exemplo frequente é o uso de ETag em conjunto com cabeçalhos que estabelecem condições do tipo “processar apenas se a entidade ainda corresponder à versão esperada”. Quando o servidor encontra um mecanismo de precondição aplicável, ele pode exigir que o cliente o envie.

Assim, o fluxo mental fica assim:

  1. O cliente tenta realizar uma operação (por exemplo, atualização).
  2. O servidor responde que falta uma precondição exigida.
  3. O cliente refaz a solicitação incluindo as condições corretas.
  4. O servidor valida as precondições e, então, processa (ou recusa por não corresponderem).

Importante: o 428 não é um “erro genérico”. Ele aponta para a necessidade de repetir a requisição com os critérios esperados.

Limitações e diferenças em relação a outros códigos

O 428 pode ser confundido com outros status que também lidam com condições, mas há diferenças úteis:

  • 428 (Precondition Required): o foco é “adicione as precondições que faltam para eu aceitar”.
  • Em situações semelhantes, outros códigos podem sinalizar conflito ou falha de condição depois que as precondições foram enviadas (por exemplo, quando a condição enviada não corresponde ao estado atual). Sem as definições exatas do servidor, você pode ver códigos diferentes dependendo do que ele valida e em que etapa.

Além disso, o 428 depende do comportamento do servidor e da política do endpoint. Isso significa que:

  • O conjunto de precondições exigidas pode variar entre APIs e serviços.
  • Um cliente que funciona em um endpoint pode falhar em outro se as precondições esperadas forem diferentes.
  • Nem sempre é possível inferir sozinho quais cabeçalhos específicos são exigidos apenas pelo número 428.

Verificações práticas para diagnosticar 428

Para lidar com 428 de forma objetiva, o ponto é investigar “qual condição o servidor estava tentando exigir”. Algumas verificações ajudam:

  1. Inspecione a resposta: além do status, procure informações adicionais no corpo e/ou cabeçalhos de resposta. Alguns servidores detalham quais condições faltaram ou como devem ser fornecidas.
  2. Compare com requisições bem-sucedidas: se você tiver uma chamada equivalente que funciona em outro contexto, compare cabeçalhos e parâmetros. Precondições costumam estar em cabeçalhos específicos.
  3. Verifique cabeçalhos condicionais: confirme se você está enviando o mecanismo de precondição que o servidor espera (por exemplo, variantes de cabeçalhos baseados em ETag/If-Match, quando aplicável). Se o servidor exige precondição e ela não está presente, isso costuma levar ao 428.
  4. Chegue ao estado correto antes de enviar a atualização: em operações de escrita, é comum que o cliente precise primeiro obter informações do recurso (como a versão/ETag) e só então enviar a requisição de modificação com a condição correspondente.
  5. Teste mudanças incrementais: se você consegue controlar a requisição, teste incluindo ou ajustando apenas os cabeçalhos de precondição. Se o servidor “passa a aceitar” quando isso muda, você confirmou a causa.

Se, após ajustar as precondições, o servidor passar a recusar por “condição não atendida”, isso geralmente indica que o servidor recebeu precondições, mas o estado atual do recurso não coincide com o que foi enviado. Nesse caso, a correção costuma ser atualizar a informação de estado (por exemplo, recuperar a versão atual) e tentar novamente.

Conceitos relacionados: concorrência e atualização segura

No pano de fundo do 428 está um conceito recorrente: controle de concorrência e consistência. Quando múltiplas operações podem ocorrer em paralelo (ou quando uma operação tenta atualizar um recurso desatualizado), o servidor pode exigir precondições para decidir se a mudança é segura.

A motivação costuma ser evitar:

  • Sobrescrita baseada em informações antigas.
  • Atualizações que presumem um estado que já mudou.
  • Divergência entre o que o cliente acredita ser o estado do recurso e o estado real no servidor.

Como o mecanismo exato varia por implementação, trate o 428 como um “contrato de requisição”: o servidor está dizendo que você precisa anexar critérios de estado para a ação prosseguir.

Observação: como não há especificação do seu servidor/endpoint aqui, pode haver incerteza sobre quais cabeçalhos específicos são exigidos. Use as verificações acima para descobrir a precondição concreta esperada pelo serviço que retornou 428.