Skip to main content

O schema que mudou sem aviso

View as MarkdownThe same page as plain textOpen in ChatGPTAsk about this pageOpen in ClaudeAsk about this page

Um campo opcional virou obrigatório sem subir de major, e o erro só apareceu no terminal de quem consumia, em três formatos diferentes.

A política de versão estava escrita, a esteira cobrava, e mesmo assim um campo opcional virou obrigatório numa 1.5.0. O motivo é chato e vale registrado: a mudança não foi no contrato, foi na validação de entrada do serviço, e a esteira só comparava os tipos publicados. O contrato continuou dizendo opcional; o serviço passou a recusar.

Como o erro chegou​

Não chegou pelo painel, nem pelo alerta. Chegou no terminal de três pessoas diferentes, em três formatos, e nenhum dos três nomeava o campo.

$ python -m equipe_alfa.sincronizar --ambiente prod
Traceback (most recent call last):
  File "/opt/alfa/sincronizar.py", line 88, in <module>
    resposta = catalogo.registrar(recurso)
  File "/opt/alfa/cliente.py", line 41, in registrar
    resposta.raise_for_status()
panlabs.catalogo.ErroDeValidacao: 422 Unprocessable Entity

$ terraform apply
Error: erro ao registrar recurso no catálogo
  status 422, corpo: {"erro":"validacao"}
  with panlabs_catalogo_recurso.bucket_relatorios,
  on catalogo.tf line 12, in resource "panlabs_catalogo_recurso" "bucket_relatorios":

$ gh run view 4821 --log-failed
Registrar no catálogo
  Erro: o registro falhou (exit 1)
  Process completed with exit code 1.

Três equipes, três horas de investigação, e a informação que faltava era a mesma em todos: qual campo.

O que a correção foi de verdade​

A correção não foi reverter: o campo precisava mesmo ser obrigatório. Foi fazer a recusa dizer o que recusou.

# antes: o corpo tinha a categoria do erro e nada mais
return Resposta(status=422, corpo={"erro": "validacao"})

# depois: o campo, o motivo e a versão do contrato que passou a exigi-lo
return Resposta(
    status=422,
    corpo={
        "erro": "validacao",
        "campo": "dono",
        "motivo": "obrigatorio_desde",
        "contrato": "2.0.0",
    },
)

A pergunta que separa uma mensagem de erro boa de uma ruim é sempre a mesma: ela diz o que fazer a seguir? 422 validacao diz que algo está errado; campo=dono contrato=2.0.0 diz para subir de versão e preencher o campo.

O que ficou​

A esteira ganhou um terceiro passo, que compara as regras de validação e não só os tipos. E ficou uma regra de redação para resposta de erro: categoria, campo e versão, sempre os três, porque quem lê a mensagem está num terminal que não tem o contrato aberto ao lado.