 |
| Bellacosa Mainframe e o status codes das api numa visão para pequenos gafanhotos |
☕ Um Café no Bellacosa Mainframe
API Status Codes sem Mistérios para Programadores COBOL
Quando um Programador Descobre que o Servidor Já Respondeu à Pergunta… Mas Ele Preferiu Consultar Três Logs, Dois Oráculos e um Monge no Deserto
No início da jornada, o jovem programador acreditava que todo erro de API era uma entidade sobrenatural.
Uma criatura invisível.
Um espírito maligno vivendo entre o frontend, o backend, o banco de dados, o firewall, o proxy reverso, o balanceador de carga e aquele serviço terceirizado que ninguém sabia exatamente quem havia contratado.
Quando a aplicação falhava, ele fazia o ritual tradicional:
Reiniciava o navegador.
Limpava o cache.
Reiniciava a aplicação.
Reiniciava o computador.
Culpava a rede.
Culpava o banco de dados.
Culpava o COBOL.
Perguntava à inteligência artificial.
Mandava uma mensagem no grupo da equipe dizendo:
“Alguém mexeu em produção?”
Então, numa tarde coberta de névoa, enquanto o vento atravessava os corredores do data center e os discos do mainframe giravam como tambores de um templo tecnológico, apareceu o velho mestre.
Ele vestia um quimono gasto, carregava uma caneca de café e segurava nas mãos uma folha contendo quatro símbolos:
2xx
3xx
4xx
5xx
O jovem programador perguntou:
— Mestre, qual é o significado desses números?
O velho respondeu:
— Pequeno gafanhoto, antes de procurar o erro no universo inteiro, leia aquilo que o servidor já lhe disse.
O programador olhou para a tela.
HTTP/1.1 404 Not Found
— Mestre, devo verificar o banco de dados?
— Não.
— O servidor Java?
— Não.
— A aplicação COBOL?
— Não.
— A temperatura da sala do data center?
— Também não.
— Então o que devo verificar?
O mestre tomou um gole de café.
— A URL.
E assim começou a verdadeira arte marcial do debugging de APIs.
O servidor não fala em enigmas
Quando uma API responde, ela não entrega somente dados.
Ela entrega uma estrutura.
Normalmente, uma resposta HTTP possui pelo menos três elementos importantes:
Status
Headers
Body
Por exemplo:
HTTP/1.1 404 Not Found
Content-Type: application/json
X-Correlation-ID: 9812-A7B3
{
"error": "Cliente não encontrado"
}
O programador iniciante frequentemente olha apenas para o corpo.
O mais apressado olha apenas para a mensagem.
O mais desesperado ignora tudo e abre os logs.
Mas o verdadeiro praticante da arte do debugging observa o conjunto.
O código 404 indica uma classe de problema.
O corpo informa um detalhe.
O cabeçalho X-Correlation-ID pode permitir encontrar a requisição nos logs.
É semelhante a analisar um ABEND em ambiente mainframe.
Receber apenas:
JOB FAILED
não é suficiente.
Você precisa saber:
Qual step?
Qual programa?
Qual return code?
Qual ABEND?
Qual dataset?
Qual mensagem?
Qual horário?
Qual execução?
Em APIs, o status HTTP é como o primeiro código do incidente.
Ele não resolve tudo, mas mostra em qual porta você deve bater.
O caminho completo de uma chamada de API
Muitos desenvolvedores imaginam uma API desta maneira:
Cliente → Servidor
Parece simples.
Quase poético.
Infelizmente, sistemas corporativos raramente possuem a delicadeza de um poema.
O caminho real pode ser:
Aplicação cliente
↓
DNS
↓
Proxy corporativo
↓
Firewall
↓
WAF
↓
CDN
↓
Load balancer
↓
API Gateway
↓
Servidor web
↓
Aplicação
↓
Banco de dados
↓
Fila
↓
Mainframe
↓
Outro serviço externo
Quando você recebe um erro, ele pode ter sido produzido por qualquer ponto dessa longa peregrinação.
Um 502, por exemplo, geralmente indica que algum intermediário tentou conversar com outro servidor e recebeu uma resposta inválida.
Um 504 indica que o intermediário esperou, esperou, acendeu uma vela, terminou um café e desistiu.
Um 401 pode ser produzido por um gateway de autenticação antes mesmo de a requisição chegar à aplicação.
Portanto, aprender os códigos HTTP é aprender a localizar o templo onde o problema provavelmente vive.
A primeira família: 1xx — o mensageiro ainda está falando
Os códigos 1xx são pouco vistos no desenvolvimento cotidiano, mas fazem parte do protocolo.
Eles indicam que alguma informação preliminar foi transmitida e que o processo continua.
100 Continue
Imagine que você pretende enviar um arquivo gigantesco para o servidor.
Antes de enviar tudo, o cliente pode perguntar:
Expect: 100-continue
O servidor responde:
HTTP/1.1 100 Continue
Em outras palavras:
“Pode continuar. Ainda não rejeitei sua requisição.”
Isso evita que o cliente envie centenas de megabytes apenas para descobrir depois que não possui autorização.
É como chegar ao portão do mosteiro com vinte caixas e perguntar:
— Posso entrar?
O porteiro responde:
— Continue.
Melhor isso do que carregar tudo até o pátio e descobrir que o templo estava fechado desde 1978.
101 Switching Protocols
Esse código indica mudança de protocolo.
A conexão começou de uma forma e continuará de outra.
É comum em situações de upgrade de comunicação.
103 Early Hints
Permite que o servidor envie pistas antecipadas para o cliente começar a preparar certos recursos antes da resposta final.
É uma espécie de mensagem do mestre:
“Ainda não terminei a explicação, mas já vá abrindo o manual.”
A segunda família: 2xx — a técnica foi executada com sucesso
Os códigos 2xx indicam sucesso sob a ótica do protocolo HTTP.
Mas existe uma diferença importante:
Sucesso HTTP não significa necessariamente sucesso de negócio.
Uma API pode responder 200 OK e, dentro do corpo, informar que uma operação comercial falhou.
Isso é possível, embora frequentemente represente uma API mal projetada.
200 OK
É o sucesso genérico.
Exemplo:
GET /clientes/123
Resposta:
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 123,
"nome": "Vagner",
"status": "ativo"
}
A requisição foi atendida e o recurso foi retornado.
No mundo COBOL, seria algo semelhante a:
Programa executado
Registro encontrado
Dados retornados
RETURN-CODE = 0
Mas tome cuidado com respostas como:
HTTP/1.1 200 OK
{
"success": false,
"message": "Cliente não encontrado"
}
O protocolo diz sucesso.
O corpo diz falha.
É como um job terminar com CC 0000 e imprimir no relatório:
NENHUM REGISTRO FOI PROCESSADO PORQUE O ARQUIVO ESTAVA CORROMPIDO
Tecnicamente terminou.
Funcionalmente, o castelo está em chamas.
A primeira lição é:
Sempre valide o conteúdo da resposta, não apenas o código.
201 Created
O código 201 indica que um novo recurso foi criado.
Requisição:
POST /clientes
Content-Type: application/json
{
"nome": "Maria",
"email": "maria@example.com"
}
Resposta:
HTTP/1.1 201 Created
Location: /clientes/845
{
"id": 845,
"nome": "Maria",
"email": "maria@example.com"
}
O cabeçalho Location informa onde o novo recurso pode ser encontrado.
Analogia mainframe:
200 = a consulta funcionou
201 = um novo registro foi gravado
É como executar um WRITE com sucesso em um arquivo VSAM e receber a chave do registro recém-criado.
202 Accepted
Este é um dos códigos mais importantes para quem conhece processamento batch.
O 202 significa:
“Recebi sua solicitação, aceitei o trabalho, mas ele ainda não terminou.”
Exemplo:
POST /relatorios/mensais
Resposta:
HTTP/1.1 202 Accepted
Location: /tarefas/98271
{
"taskId": 98271,
"status": "PROCESSING"
}
Isto é praticamente o equivalente web de:
JOB SUBMITTED
Submeter o job não significa que ele terminou.
Ele pode estar:
INPUT
EXECUTION
OUTPUT
HELD
ABENDED
O iniciante vê 202 e comemora.
O mestre pergunta:
— Onde você consulta o resultado?
O 202 normalmente deve ser acompanhado por algum mecanismo de acompanhamento:
GET /tarefas/98271
Resposta posterior:
{
"taskId": 98271,
"status": "COMPLETED"
}
Ou, em um dia menos agradável:
{
"taskId": 98271,
"status": "FAILED",
"error": "Database unavailable"
}
204 No Content
O 204 significa sucesso sem corpo de resposta.
Exemplo:
DELETE /clientes/845
Resposta:
HTTP/1.1 204 No Content
A operação funcionou.
Não existe JSON.
Não existe XML.
Não existe mensagem de parabéns.
O servidor apenas cruza os braços e diz:
“Feito.”
Isso provoca um erro clássico em JavaScript:
const data = await response.json();
Se a resposta é 204, não existe JSON.
Então o cliente pode falhar tentando ler algo que nunca foi enviado.
Forma mais segura:
if (response.status === 204) {
return null;
}
return await response.json();
O programador COBOL compreenderá imediatamente.
É como um programa que termina com RETURN-CODE = 0, mas não gera relatório porque não havia nada a imprimir.
A terceira família: 3xx — o caminho mudou
Os códigos 3xx indicam redirecionamento, reutilização de cache ou mudança de localização.
O servidor não está necessariamente dizendo que existe um erro.
Ele pode estar dizendo:
“Aquilo que você procura está em outro lugar.”
301 Moved Permanently
O recurso mudou definitivamente.
Exemplo:
GET /api/v1/clientes
Resposta:
HTTP/1.1 301 Moved Permanently
Location: /api/v2/clientes
A antiga rota foi substituída.
Isso pode ocorrer por:
O erro aparece quando o cliente não segue redirecionamentos automaticamente.
O navegador geralmente segue.
Uma aplicação antiga talvez não.
Um programa batch escrito quando televisores ainda possuíam madeira nas laterais pode simplesmente receber o 301 e ficar olhando para ele como um discípulo diante de uma porta fechada.
302 Found
O 302 representa normalmente um redirecionamento temporário.
Um caso comum é autenticação.
Você chama:
GET /api/clientes
O servidor responde:
HTTP/1.1 302 Found
Location: /login
O navegador segue o redirecionamento e recebe:
HTTP/1.1 200 OK
Content-Type: text/html
Então o desenvolvedor reclama:
“A API está retornando HTML em vez de JSON!”
Na realidade, a API redirecionou para a página de login, e o cliente seguiu automaticamente.
A sequência real foi:
GET /api/clientes
↓
302 /login
↓
200 página HTML
Por isso, ferramentas como curl ajudam muito.
curl -v https://api.exemplo.com/clientes
O modo verboso revela os passos intermediários.
304 Not Modified
O 304 está relacionado a cache.
Ele significa:
“O conteúdo não mudou. Use a cópia que você já possui.”
Primeira requisição:
GET /imagem.png
Resposta:
HTTP/1.1 200 OK
ETag: "abc123"
Requisição posterior:
GET /imagem.png
If-None-Match: "abc123"
Resposta:
HTTP/1.1 304 Not Modified
O servidor não envia novamente o arquivo.
O navegador usa a versão em cache.
Isso economiza:
banda;
tempo;
processamento;
custo;
tráfego.
Mas também pode criar o famoso bug fantasma:
“Eu alterei o JavaScript, mas o navegador insiste em executar a versão antiga.”
Nesse momento, o culpado pode ser:
Cache-Control
ETag
CDN
Proxy
Service Worker
Cache do navegador
O jovem programador apaga a aplicação inteira.
O mestre apenas pressiona Ctrl + Shift + R.
A quarta família: 4xx — a requisição chegou com problemas
Os códigos 4xx indicam que existe algum impedimento associado à requisição do cliente.
Isso não significa que o frontend é culpado.
Pode haver documentação errada, configurações incorretas, permissões mal atribuídas ou contratos incompatíveis.
O código apenas indica onde começar.
400 Bad Request
O 400 significa requisição inválida.
Possíveis causas:
Exemplo:
{
"nome": "Vagner",
"idade": 52,
}
A vírgula final pode tornar o JSON inválido.
Outro exemplo:
Content-Type: text/plain
quando a API espera:
Content-Type: application/json
Analogia COBOL:
05 WS-DATA PIC 9(8).
Entrada recebida:
23/07/2026
O humano compreende.
O programa não.
O layout esperava oito dígitos, talvez:
20260723
Quando receber 400, verifique:
Método
URL
Query string
Headers
Content-Type
JSON
Tipos
Datas
Campos obrigatórios
Codificação
401 Unauthorized
O 401 indica problema de autenticação.
Tradução prática:
“Não consegui validar corretamente quem você é.”
Causas comuns:
Exemplo:
Authorization: Bearer token-expirado
Resposta:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Uma situação curiosa ocorre com tokens JWT.
O token pode possuir:
Data de emissão
Data de expiração
Emissor
Audiência
Escopos
Assinatura
Se o relógio da máquina cliente estiver alguns minutos errado, um token válido pode parecer expirado ou ainda não válido.
Às vezes o grande vilão da autenticação não é um hacker internacional.
É o relógio do servidor.
403 Forbidden
O 403 significa que a identidade pode ser conhecida, mas a operação não é permitida.
Diferença essencial:
401 = não consegui autenticar você
403 = autentiquei você, mas você não possui autorização
Exemplo:
Usuário: Vagner
Perfil: CONSULTA
Operação: DELETE
Resposta:
HTTP/1.1 403 Forbidden
No mundo mainframe, pense em RACF:
Usuário reconhecido
Senha aceita
Acesso ao recurso negado
Você entrou no prédio.
Possui crachá.
Mas a porta da sala de produção continua fechada.
E o segurança não parece disposto a discutir filosofia.
404 Not Found
O 404 significa que a rota ou o recurso não foi encontrado.
Pode ser:
URL errada
Endpoint inexistente
ID inexistente
Versão incorreta
Ambiente errado
Deploy incompleto
Maiúscula ou minúscula diferente
Context path ausente
Exemplo:
GET /clientes/999999
Resposta:
HTTP/1.1 404 Not Found
Existem duas situações diferentes.
A rota não existe
/api/clientez/123
O endpoint foi digitado incorretamente.
O recurso não existe
/api/clientes/999999
O endpoint existe, mas o cliente não.
Outra armadilha:
O endpoint existe em desenvolvimento:
/api/v2/clientes
Mas produção só possui:
/api/v1/clientes
O código está no repositório.
O pipeline ficou verde.
A apresentação para a diretoria foi magnífica.
O endpoint, entretanto, não foi implantado.
O 404 está apenas dizendo:
“Aqui, neste ambiente, nesta rota, isso não existe.”
405 Method Not Allowed
A rota existe, mas o método HTTP não é permitido.
Exemplo:
POST /clientes/123
Resposta:
HTTP/1.1 405 Method Not Allowed
Allow: GET, PUT, DELETE
Diferença:
404 = não encontrei a rota ou o recurso
405 = encontrei a rota, mas esse verbo não é aceito
É como chegar à agência correta, falar com a pessoa correta e pedir a operação errada.
409 Conflict
O 409 indica conflito com o estado atual do recurso.
Exemplos:
Imagine:
Cliente A lê:
{
"id": 100,
"saldo": 500,
"versao": 7
}
Cliente B altera o registro.
Agora a versão é 8.
Cliente A tenta salvar usando a versão 7.
Resposta:
HTTP/1.1 409 Conflict
A requisição é válida.
O problema é que ela nasceu em um passado que já não existe.
É praticamente uma viagem no tempo corporativa.
415 Unsupported Media Type
O formato enviado não é aceito.
Você envia:
Content-Type: application/xml
Mas a API aceita apenas:
Content-Type: application/json
Resposta:
HTTP/1.1 415 Unsupported Media Type
Antes de investigar o banco de dados, examine o cabeçalho.
Muitos incidentes terminam com uma frase humilhante:
“Estávamos enviando XML para um endpoint JSON.”
422 Unprocessable Content
O JSON está bem formado, mas os dados não passam nas regras.
Exemplo:
{
"nome": "Ana",
"idade": -17,
"email": "banana"
}
A sintaxe é válida.
Os valores não são.
Resposta:
HTTP/1.1 422 Unprocessable Content
{
"errors": [
{
"field": "idade",
"message": "Valor inválido"
},
{
"field": "email",
"message": "Formato inválido"
}
]
}
Distinção prática:
400 = não consegui interpretar corretamente
422 = interpretei, mas não posso aceitar
Nem todas as APIs seguem essa divisão, mas ela é útil.
429 Too Many Requests
O cliente ultrapassou o limite de requisições.
Resposta:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Tradução:
“Pare por sessenta segundos.”
O cliente mal projetado interpreta:
“Tente imediatamente mais quinhentas vezes.”
E assim nasce um pequeno ataque de negação de serviço produzido pela própria aplicação.
A solução correta inclui:
Exemplo:
1ª falha → espera 1 segundo
2ª falha → espera 2 segundos
3ª falha → espera 4 segundos
4ª falha → espera 8 segundos
Com jitter, adiciona-se um pequeno intervalo aleatório.
Isso evita que milhares de clientes voltem exatamente ao mesmo tempo, como discípulos famintos quando alguém anuncia que o café está pronto.
A quinta família: 5xx — o servidor tropeçou
Os códigos 5xx indicam falha do lado servidor ou de alguma infraestrutura associada.
Mas cuidado:
Uma requisição específica pode acionar um bug do servidor.
O cliente pode ser o gatilho, embora a responsabilidade técnica continue sendo da aplicação.
500 Internal Server Error
É o erro genérico.
Pode representar:
Resposta ruim:
HTTP/1.1 500 Internal Server Error
Something went wrong
Resposta melhor:
HTTP/1.1 500 Internal Server Error
X-Correlation-ID: A7C9-2218
{
"status": 500,
"message": "Não foi possível concluir a operação",
"correlationId": "A7C9-2218"
}
O correlation ID é extremamente importante.
Ele permite localizar a mesma transação nos logs de:
Gateway
Aplicação
Banco
Fila
Mainframe
Serviço externo
O usuário não deve receber stack trace, senha, SQL completo ou detalhes internos.
Isso seria como imprimir o conteúdo do dump de produção na porta da empresa.
502 Bad Gateway
Um gateway ou proxy recebeu uma resposta inválida do servidor posterior.
Fluxo:
Cliente
↓
Gateway
↓
Backend
O gateway está ativo.
O backend falhou, respondeu de forma inválida ou não aceitou a conexão.
Causas:
serviço caiu;
DNS interno falhou;
porta errada;
certificado inválido;
container reiniciando;
conexão recusada;
resposta malformada.
Tradução kung fu:
O mensageiro chegou ao portão, mas o mestre do templo não respondeu corretamente.
503 Service Unavailable
O serviço está temporariamente indisponível.
Possíveis causas:
Resposta:
HTTP/1.1 503 Service Unavailable
Retry-After: 120
Diferença:
500 = ocorreu uma falha interna inesperada
503 = o serviço não consegue atender agora
Em ambiente com containers, um 503 pode significar:
Load balancer funcionando
Nenhum pod saudável disponível
O restaurante está aberto.
A cozinha desapareceu.
504 Gateway Timeout
O gateway esperou pelo backend, mas o tempo limite expirou.
Fluxo:
Cliente
↓
Gateway
↓
API
↓
Banco
↓
Mainframe
O gateway espera 30 segundos.
O backend demora 45.
Resultado:
HTTP/1.1 504 Gateway Timeout
O detalhe mais valioso pode ser o tempo.
Se o erro ocorre sempre em exatamente 30 segundos, existe grande chance de um timeout configurado nessa camada.
Por exemplo:
Gateway timeout: 30 s
API timeout: 60 s
Banco responde em 42 s
A aplicação ainda trabalha quando o gateway abandona a conversa.
A solução não é automaticamente aumentar o timeout.
Talvez seja melhor:
Aumentar o timeout sem investigar é como ensinar o discípulo a esperar mais tempo diante de uma porta emperrada.
O perigo dos retries
Nem toda chamada deve ser repetida.
Métodos normalmente idempotentes
GET
PUT
DELETE
Em princípio, repetir deve conduzir ao mesmo estado final.
POST normalmente não é idempotente
Exemplo:
POST /pagamentos
O servidor processa o pagamento.
A resposta demora.
O gateway devolve 504.
O cliente repete.
Resultado possível:
Pagamento 1 criado
Pagamento 2 criado
Cliente furioso
Reunião extraordinária
PowerPoint com 74 slides
Para evitar duplicidade, APIs podem aceitar:
Idempotency-Key: pedido-82719-pagamento-1
Se a mesma operação for repetida, o servidor reconhece a chave.
Retries fazem mais sentido em códigos como:
408
429
502
503
504
Mesmo assim, devem possuir:
limite de tentativas;
backoff;
jitter;
controle de duplicidade;
respeito ao Retry-After.
Não repita cegamente:
400
401
403
404
409
422
Uma requisição errada repetida cem vezes continua errada.
Ela apenas fica mais barulhenta.
Passo a passo para investigar uma API
Quando surgir um erro, siga esta ordem.
Passo 1 — veja o método
GET
POST
PUT
PATCH
DELETE
A rota pode aceitar apenas alguns métodos.
Passo 2 — confira a URL completa
Verifique:
Protocolo
Domínio
Porta
Context path
Versão
Endpoint
Query string
Barra final
Maiúsculas e minúsculas
Passo 3 — leia o status
Classifique:
1xx → continuação
2xx → sucesso
3xx → redirecionamento ou cache
4xx → problema associado à requisição
5xx → problema no servidor ou infraestrutura
Passo 4 — leia os headers
Especialmente:
Authorization
Content-Type
Accept
Location
Retry-After
ETag
X-Correlation-ID
Passo 5 — leia o corpo
A mensagem pode indicar:
Campo inválido
Token expirado
Recurso ausente
Versão conflitante
Limite excedido
Passo 6 — observe o tempo
Erro em 10 ms → falha imediata
Erro em 30 s exatos → timeout provável
Erro variável → dependência instável
Passo 7 — procure o correlation ID
Use-o nos logs.
Passo 8 — reproduza com ferramenta simples
Exemplo:
curl -v \
-H "Authorization: Bearer TOKEN" \
-H "Accept: application/json" \
https://api.exemplo.com/clientes/123
O curl -v mostra:
conexão;
certificados;
headers enviados;
headers recebidos;
redirecionamentos;
status;
detalhes úteis.
Passo 9 — só então abra os logs
Os logs não devem ser o primeiro lugar.
Devem ser o lugar correto após o status indicar a direção.
O algoritmo COBOL do guerreiro HTTP
Um programador COBOL pode pensar desta forma:
EVALUATE TRUE
WHEN HTTP-STATUS >= 100
AND HTTP-STATUS < 200
DISPLAY 'RESPOSTA INFORMATIVA'
WHEN HTTP-STATUS >= 200
AND HTTP-STATUS < 300
DISPLAY 'SUCESSO HTTP'
PERFORM VALIDAR-RESULTADO-FUNCIONAL
WHEN HTTP-STATUS >= 300
AND HTTP-STATUS < 400
DISPLAY 'VERIFICAR REDIRECT OU CACHE'
PERFORM ANALISAR-LOCATION
WHEN HTTP-STATUS >= 400
AND HTTP-STATUS < 500
DISPLAY 'VERIFICAR REQUEST'
PERFORM ANALISAR-AUTH
PERFORM ANALISAR-HEADERS
PERFORM ANALISAR-BODY
WHEN HTTP-STATUS >= 500
AND HTTP-STATUS < 600
DISPLAY 'VERIFICAR SERVIDOR'
PERFORM LOCALIZAR-CORRELATION-ID
PERFORM CONSULTAR-LOGS
WHEN OTHER
DISPLAY 'STATUS INESPERADO'
END-EVALUATE.
Mas o mestre acrescentaria:
IF HTTP-STATUS = 200
AND BUSINESS-RESULT NOT = 'SUCCESS'
DISPLAY 'HTTP OK, NEGOCIO NAO OK'
END-IF.
Porque o sábio sabe que nem todo 200 representa felicidade.
Curiosidades do templo HTTP
Curiosidade 1 — 401 possui um nome confuso
401 Unauthorized é usado principalmente para falha de autenticação.
O código mais associado à falta de autorização é 403.
O nome histórico permaneceu, e agora gera confusão em várias gerações de desenvolvedores.
Curiosidade 2 — 404 pode proteger informações
Alguns sistemas devolvem 404 em vez de 403 para não revelar que determinado recurso existe.
Em vez de dizer:
“Existe, mas você não pode acessar.”
o sistema responde:
“Nunca ouvi falar.”
É o equivalente digital do monge que esconde o pergaminho atrás das costas.
Curiosidade 3 — 418 existe como brincadeira
O código 418 I’m a Teapot nasceu como uma piada relacionada a um protocolo fictício de controle de bules de café.
Não deve ser usado como erro sério de produção.
Embora, em certas empresas, talvez descreva com precisão a maturidade da arquitetura.
Curiosidade 4 — 200 pode esconder desastre
Algumas APIs antigas retornam 200 para tudo.
Exemplo:
{
"status": "ERROR",
"message": "Database unavailable"
}
Isso dificulta:
monitoramento;
alertas;
métricas;
retries;
tratamento automático.
O protocolo foi criado para comunicar semântica.
Ignorá-lo é como comprar um painel de instrumentos e cobrir todos os indicadores com fita adesiva.
Curiosidade 5 — o tempo é um código invisível
Um 500 em 5 milissegundos e um 500 em 60 segundos provavelmente possuem causas diferentes.
O tempo de resposta é quase um segundo status.
Easter egg: o mestre e o código 404
Conta-se que um jovem discípulo passou três dias procurando um endpoint.
Ele verificou:
banco de dados;
certificados;
filas;
firewall;
mainframe;
memória;
CPU;
logs;
DNS;
fases da lua.
Ao final, o mestre perguntou:
— Qual URL você chamou?
O discípulo respondeu:
/api/v1/cilentes
O mestre permaneceu em silêncio.
O discípulo percebeu a troca de letras.
Perguntou:
— Por que não me avisou antes?
O mestre respondeu:
— Eu avisei.
— Quando?
— No primeiro 404.
Naquela noite, o discípulo aprendeu duas lições:
O servidor fala.
O ego do desenvolvedor nem sempre escuta.
A regra final do Bellacosa Mainframe
Guarde este mapa:
1xx → continue observando
2xx → confirme o resultado
3xx → siga o caminho
4xx → revise a requisição
5xx → investigue o servidor
Depois aprofunde:
Status
+ método
+ URL
+ headers
+ body
+ duração
+ correlation ID
= diagnóstico
O código HTTP não é a solução completa.
Ele é a primeira pista.
Ele não diz necessariamente qual linha falhou, qual tabela travou ou qual container decidiu abandonar esta dimensão.
Mas reduz o universo de possibilidades.
Em vez de perguntar:
“O que pode estar errado em toda a arquitetura?”
você pergunta:
“Por que este cliente recebeu um 401?”
ou:
“Qual upstream provocou este 502?”
ou:
“Por que a chamada sempre termina em 504 após 30 segundos?”
A pergunta fica menor.
A investigação fica objetiva.
O incidente deixa de ser uma lenda oriental contada por desenvolvedores apavorados ao redor de um monitor.
E torna-se engenharia.
No último episódio, o jovem programador recebeu uma nova mensagem:
HTTP/1.1 403 Forbidden
A equipe começou a correr.
Um administrador abriu os logs.
Outro reiniciou o servidor.
Alguém sugeriu aumentar a memória.
Um consultor propôs migrar tudo para Kubernetes.
O jovem permaneceu sentado.
Tomou um gole de café.
Abriu o token.
Verificou os escopos.
Descobriu que o usuário possuía permissão de leitura, mas não de exclusão.
Corrigiu a autorização.
A chamada retornou:
HTTP/1.1 204 No Content
O velho mestre observou de longe e perguntou:
— O que a API disse?
O programador respondeu:
— Nada.
O mestre sorriu.
— Então finalmente funcionou.
