Status codes que dizem a verdade

Resposta esperada

200 com erro no corpo quebra tudo que depende do status: caches, proxies, clientes HTTP, monitoramento — todos acham que deu certo. O status é a primeira informação e tem que ser honesto. Guia rápido: 400 (requisição malformada — JSON inválido, faltou campo obrigatório); 401 (não autenticado — sem credencial ou credencial inválida); 403 (autenticado mas sem permissão pra isso); 404 (recurso não existe — ou, às vezes, 'não existe pra você' pra não vazar); 409 (conflito de estado — criar algo que já existe, edição concorrente); 422 (sintaxe ok mas semanticamente inválido — e-mail com formato certo mas já usado, regra de negócio violada). 5xx é 'a culpa é do servidor'; nunca use 5xx pra erro de validação do cliente.