Todo mundo decora o 200 e o 404. Depois disso a conversa fica nebulosa, e aí alguém devolve 200 OK com {"erro": "deu ruim"} no corpo e o cliente da API passa a vida achando que está tudo bem.

Então vamos combinar: cada código é uma frase curta que o servidor está falando. Se você souber a frase, nunca mais escolhe errado.

A regra do primeiro dígito#

O primeiro número já conta a história quase toda:

Essa divisão entre 4xx e 5xx é a parte que importa mais. Ela decide quem vai ser acordado às três da manhã.

200 OK#

Funcionou. Não tem muito o que falar.

O problema do 200 é o abuso: ele virou o padrão de quem não quis pensar. Se a requisição falhou, devolver 200 com uma mensagem de erro no JSON não está "simplificando o cliente": está obrigando todo mundo a abrir o corpo da resposta para descobrir o que aconteceu. E algum cliente vai esquecer.

Dois irmãos que resolvem a sua vida

Use 201 Created quando a requisição criou um recurso, e devolva o Location apontando para ele. Use 204 No Content quando deu certo e não há nada para mandar de volta, como um DELETE. Seu front agradece.

301 Moved Permanently#

Mudei de endereço e não volto mais. Navegadores e buscadores levam isso a sério: eles guardam a informação e param de visitar o endereço antigo.

É aí que mora o perigo. Um 301 feito por engano fica em cache no navegador de quem visitou, e você não tem como pedir de volta. Quando estiver testando redirecionamento, use 302, ou melhor, 307, que preserva o método da requisição. Quando tiver certeza absoluta, troque para 301.

404 Not Found#

O famoso. Não encontrei nada nesse endereço.

Tem um detalhe elegante aqui que pouca gente usa de propósito: 404 é a resposta certa quando o recurso existe mas a pessoa não deveria nem saber disso. Devolver 403 Forbidden confirma que o recurso está lá, e isso já é informação demais. GitHub faz exatamente isso com repositórios privados.

404 não é 400

404 é "esse endereço não leva a nada". 400 Bad Request é "entendi o endereço, mas o que você mandou está malformado". Trocar um pelo outro confunde quem está depurando sua API às duas da manhã.

418 I'm a teapot#

Esse veio da RFC 2324, um protocolo de brincadeira para cafeteiras publicado em primeiro de abril de 1998. A ideia: se você pedir café para um bule de chá, ele responde 418.

Já tentaram remover o código das implementações mais de uma vez. A internet reagiu tão mal que ele continua lá até hoje. Não use em produção, mas saiba que existe, porque uma hora você vai ver um numa resposta e vai rir sozinho.

500 Internal Server Error#

Algo explodiu do meu lado. É o status mais honesto da lista e o mais inútil para quem recebe: ele não diz nada além de "falhou aqui dentro".

Isso é intencional. Vazar o stack trace numa resposta é entregar a estrutura interna do seu sistema para qualquer um. O lugar da mensagem detalhada é o seu log, com um identificador de correlação que você devolve para a pessoa:

{
  "error": "internal_error",
  "requestId": "7f3c9a21"
}

Aí quem está integrando te manda o requestId, você busca no log e descobre em dez segundos o que levaria uma hora de ida e volta.

O 503 é mais gentil

Quando a falha é temporária (deploy em andamento, dependência fora do ar, rate limit de infraestrutura), 503 Service Unavailable com o header Retry-After diz ao cliente exatamente quando tentar de novo. Isso é muito melhor que deixar ele tentando em loop contra um 500.

O resumo que eu colaria na parede#

• Deu certo e criou algo? 201, com Location.
• Deu certo e não tem o que devolver? 204.
• O cliente mandou porcaria? 400.
• Não sei quem é você? 401. Sei quem é e você não pode? 403.
• Não quero nem confirmar que isso existe? 404.
• Explodiu aqui? 500. Explodiu aqui mas já volta? 503 com Retry-After.

Nenhuma dessas escolhas é sobre purismo. É sobre a pessoa do outro lado conseguir descobrir o que fazer sem precisar te chamar no WhatsApp.

Quando decidi transformá-lo em blog, o modelo deixou de servir, e o motivo não é performance.

O problema não é o Google, é o compartilhamento#

A primeira reação de todo mundo é "mas o Google executa JavaScript". Executa mesmo. O problema está em outro lugar.

As meta tags de um SPA vivem em um único index.html:

<meta property="og:title" content="Carlos Eduardo Ferreira | Software Engineer" />
<meta property="og:description" content="Software Engineer no Rio de Janeiro..." />

Esse arquivo é o mesmo para todas as rotas. Então, quando alguém compartilha /blog/meu-artigo no LinkedIn, no X ou no WhatsApp, o crawler lê o HTML servido (nunca o resultado depois do React rodar) e mostra o preview genérico do portfólio. Todo artigo fica com o mesmo título e a mesma descrição.

Atualizar document.title em um efeito não resolve:

useEffect(() => {
  document.title = post.title; // o crawler social nunca chega aqui
}, [post.title]);

Crawlers de rede social quase nunca executam JavaScript. Para eles, seu blog inteiro é uma página só.

Três caminhos#

Avaliei três opções:

Astro é a escolha canônica para sites de conteúdo, e eu recomendaria para quem começa do zero. No meu caso havia um shell que eu gostava, com sidebar colapsável, background reativo ao mouse e animações, e reescrevê-lo como layout Astro era jogar trabalho fora para resolver um problema de meta tags.

O que eu fiz#

Mantive a SPA e adicionei um passo depois do build. O npm run build passou a ter três etapas:

{
  "build": "npm run build:client && npm run build:server && npm run prerender",
  "build:client": "vite build",
  "build:server": "vite build --ssr",
  "prerender": "node scripts/prerender.mjs"
}

A segunda etapa compila a mesma aplicação para rodar em Node. A terceira percorre cada rota conhecida, renderiza com renderToString, injeta as meta tags daquela rota e grava um arquivo HTML de verdade:

dist/public/
├── index.html
├── blog/index.html
├── blog/meu-artigo/index.html
├── til/index.html
├── rss.xml
└── sitemap.xml

O resultado: cada artigo tem título, descrição, og:image e JSON-LD próprios no HTML servido. A SPA continua existindo: ela hidrata por cima do HTML pré-renderizado e a navegação interna segue instantânea.

O detalhe que quase me pegou#

O corpo dos artigos é carregado sob demanda, em um chunk separado. Isso é ótimo para o tamanho do bundle e terrível para hidratação: o servidor renderiza o texto completo, e o cliente, no primeiro render, ainda não tem esse módulo em memória. React reclama da divergência e descarta o HTML.

A solução foi esperar o módulo antes de hidratar:

async function start() {
  await preloadBodyForPath(window.location.pathname);

  if (container.firstElementChild) hydrateRoot(container, <App />);
  else createRoot(container).render(<App />);
}

Como o HTML pré-renderizado já está visível na tela, essa espera é invisível para quem lê.

O que eu levaria para o próximo projeto#

Se o site vai ter conteúdo desde o começo, use um framework que gere HTML estático e pare de pensar nisso. Se o conteúdo chega depois, como no meu caso, pré-renderizar rotas conhecidas é um caminho curto e honesto, e você não precisa abandonar nada do que já construiu.

Eu queria contar os privados. Sem expor nada deles.

As três regras que me impus#

1. Nenhum token chega ao navegador.
2. Nenhum nome, descrição ou URL de repositório privado é publicado.
3. Nenhum serviço de terceiro recebe meu token.

A terceira regra elimina os geradores de badge prontos. As duas primeiras eliminam qualquer chamada à API feita pelo cliente.

A forma do dado importa mais que o acesso#

A decisão que resolve o problema não é sobre autenticação, é sobre o que fica salvo. Em vez de guardar uma lista de repositórios, eu guardo só o agregado:

{
  "summary": { "repositoryCount": 32, "stars": 1 },
  "activity": { "commits": 94, "pullRequests": 6, "issues": 0, "reviews": 0 },
  "languages": [
    { "name": "TypeScript", "color": "#3178c6", "bytes": 141815, "percentage": 62.71 }
  ]
}

Um repositório privado contribui com bytes para o total de uma linguagem e com +1 na contagem. Ele não aparece em lugar nenhum de forma identificável: nem o nome, nem quando foi atualizado, nem quantas estrelas tem. O número agregado não é reversível.

Onde o token vive#

A coleta roda em um GitHub Action diário, nunca no navegador:

- name: Generate GitHub statistics
  run: node scripts/update-github-stats.mjs
  env:
    GITHUB_STATS_TOKEN: ${{ secrets.GH_STATS_TOKEN || github.token }}
    INCLUDE_PRIVATE: ${{ secrets.GH_STATS_TOKEN != '' }}

Duas coisas acontecem aqui que vale destacar.

A primeira é o fallback: se o secret GH_STATS_TOKEN não existe, o workflow usa o GITHUB_TOKEN temporário do Actions e produz apenas dados públicos. O site nunca quebra por falta de configuração; ele só fica menos completo.

A segunda é que INCLUDE_PRIVATE é derivado da existência do secret, não escrito à mão. Não existe estado em que eu peça dados privados sem ter credencial para isso.

Uma verificação que vale o esforço#

A query GraphQL pede viewer { login } junto com os dados. Com isso o script confere se o token pertence mesmo ao usuário configurado:

if (includePrivate && data.viewer.login.toLowerCase() !== username.toLowerCase()) {
  throw new Error("GH_STATS_TOKEN não pertence ao usuário configurado.");
}

Parece paranoia até você trocar um token e passar a publicar silenciosamente a atividade de outra conta. Falhar o build é muito melhor que acertar por acidente.

O que o navegador recebe#

Um arquivo JSON estático, commitado no repositório e servido junto com o site. O cliente faz um fetch e, se algo der errado, cai em um fallback compilado no bundle:

export function useGitHubStats() {
  const [stats, setStats] = useState<GitHubStats>(fallbackGitHubStats);
  // ...
}

Nenhuma chave, nenhuma chamada autenticada, nenhuma dependência de terceiro em tempo de execução. A página carrega igual se a API do GitHub estiver fora do ar.

O custo disso#

O dado tem até 24 horas de atraso. Para um portfólio, isso é irrelevante, e é um preço pequeno por não ter segredo nenhum rodando no navegador de quem visita.