Quando estamos desenvolvendo uma API REST, os códigos de status HTTP são fundamentais para indicar ao cliente se uma requisição foi executada com sucesso ou se ocorreu algum tipo de erro.

Apesar de parecerem simples, muitos desenvolvedores iniciantes utilizam os códigos incorretamente, retornando sempre 200 OK ou utilizando 400 Bad Request para qualquer situação.

Neste artigo vamos construir uma API utilizando Node.js e Express, entender quando utilizar cada código de status HTTP e aprender boas práticas utilizadas em aplicações reais.

---

Assista à aula completa

Se preferir acompanhar todo o desenvolvimento passo a passo, assista à aula completa no YouTube.

🎥 Live completa:

---

O que são Status HTTP?

Sempre que um navegador, aplicativo ou sistema faz uma requisição para um servidor, este responde utilizando um código HTTP.

Esse código informa ao cliente o resultado da operação.

Por exemplo:

• A requisição foi executada com sucesso?
• O usuário não possui autorização?
• O recurso não existe?
• Houve erro interno no servidor?

Cada situação possui um código específico.

---

Principais categorias de Status HTTP

Os códigos são divididos em cinco grupos principais.

1xx — Informativos

Utilizados para informar que a requisição foi recebida.

São pouco utilizados no desenvolvimento cotidiano.

---

2xx — Sucesso

Indicam que tudo ocorreu corretamente.

Os mais comuns são:

• 200 OK
• 201 Created

---

3xx — Redirecionamento

Utilizados quando um recurso foi movido ou redirecionado.

Exemplo:

• 301
• 302

---

4xx — Erro do Cliente

O problema ocorreu na requisição enviada pelo cliente.

Exemplos:

• 400
• 401
• 403
• 404
• 422

---

5xx — Erro do Servidor

O servidor encontrou um erro durante o processamento.

Exemplo:

• 500 Internal Server Error

---

Status 200 OK

O código 200 OK deve ser utilizado quando a operação foi executada com sucesso.

Exemplo:

• Buscar usuários
• Listar produtos
• Consultar um cadastro

res.status(200).json(usuario);

---

Status 201 Created

Quando um novo recurso é criado, o código correto é 201 Created.

Exemplo:

Cadastro de um novo usuário.

res.status(201).json(novoUsuario);

Muitos desenvolvedores retornam 200, mas o correto é utilizar 201, informando que um novo recurso foi criado.

---

Status 400 Bad Request

O código 400 indica que a requisição enviada possui informações inválidas.

Exemplos:

• JSON inválido
• Campo obrigatório ausente
• Formato incorreto

return res.status(400).json({
    mensagem: "Dados inválidos."
});

---

Status 401 Unauthorized

Utilizado quando o usuário ainda não foi autenticado.

Exemplo:

Token JWT inexistente ou inválido.

return res.status(401).json({
    mensagem: "Token inválido."
});

---

Status 403 Forbidden

Neste caso o usuário está autenticado, porém não possui permissão para acessar determinado recurso.

Exemplo:

Usuário comum tentando acessar uma área administrativa.

---

Status 404 Not Found

O recurso solicitado não existe.

Exemplo:

Buscar um produto utilizando um ID inexistente.

return res.status(404).json({
    mensagem: "Produto não encontrado."
});

---

Status 422 Unprocessable Entity

Um dos códigos mais esquecidos pelos iniciantes.

O 422 é utilizado quando os dados possuem formato correto, porém não passam nas regras de negócio.

Exemplo:

• Email inválido
• CPF inválido
• Senha muito pequena

return res.status(422).json({
    mensagem: "Email inválido."
});

---

Status 500 Internal Server Error

Este código representa um erro interno do servidor.

Uma boa prática importante é:

Nunca retornar o erro real para o usuário.

Errado:

{
    "erro": "Cannot read property..."
}

Correto:

{
    "mensagem": "Erro interno do servidor."
}

O erro verdadeiro deve ser registrado apenas nos logs da aplicação utilizando:

console.error(error);

ou ferramentas como:

• Winston
• Pino
• Morgan

---

Testando a API com Thunder Client

Durante a aula utilizamos o Thunder Client para testar todas as rotas da API.

Foram simuladas situações reais para demonstrar:

• sucesso (200)
• criação (201)
• dados inválidos (400)
• autenticação (401)
• autorização (403)
• recurso inexistente (404)
• validação (422)
• erro interno (500)

Esse tipo de teste facilita muito o desenvolvimento de APIs REST.

---

Boas práticas

Durante o desenvolvimento procure sempre:

• utilizar o código HTTP correto;
• nunca retornar erros internos para o cliente;
• validar dados tanto no frontend quanto no backend;
• utilizar logs para registrar erros;
• testar todas as rotas antes da publicação.

Essas práticas tornam a API mais segura, organizada e fácil de manter.

---

Conclusão

Entender os códigos de status HTTP é um dos conhecimentos mais importantes para qualquer desenvolvedor backend.

Mais do que decorar números, é fundamental compreender quando utilizar cada código para criar APIs REST padronizadas e profissionais.

Se você está aprendendo Node.js, Express ou desenvolvimento de APIs, dominar esses códigos fará diferença na qualidade dos seus projetos.