Status HTTP: Guia Completo dos Códigos de Resposta em APIs REST (2xx, 4xx e 5xx)

Status HTTP: Guia completo dos códigos de resposta em APIs REST

Status HTTP: Guia Completo dos Códigos de Resposta em APIs REST

Os status HTTP são códigos numéricos retornados pelo servidor para indicar o resultado de uma requisição. Eles são essenciais para quem trabalha com APIs REST, pois permitem entender rapidamente se uma operação foi bem-sucedida, se houve erro do cliente ou falha do servidor.

Ao interpretar corretamente os status HTTP, você consegue criar integrações mais robustas, tratar erros com precisão e melhorar a experiência do usuário final.

Estrutura de uma resposta HTTP

Uma resposta HTTP é composta por três partes principais:

  • Status Code: código numérico que define o resultado
  • Headers: metadados da resposta (tipo, cache, autenticação)
  • Body: dados retornados, normalmente em JSON

Exemplo de resposta:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true,
  "data": {...}
}

2xx — Status HTTP de Sucesso

Os códigos 2xx indicam que a requisição foi processada corretamente.

  • 200 OK: requisição executada com sucesso e retorno de dados
  • 201 Created: recurso criado com sucesso (ideal para POST)
  • 202 Accepted: requisição aceita, mas ainda em processamento
  • 204 No Content: sucesso sem necessidade de retorno no corpo

3xx — Status HTTP de Redirecionamento

Os códigos 3xx aparecem quando o servidor indica que o recurso mudou ou que o cliente deve usar cache.

  • 301 Moved Permanently: URL alterada permanentemente
  • 302 Found: redirecionamento temporário
  • 304 Not Modified: recurso não mudou, pode usar cache

4xx — Status HTTP de Erros do Cliente

Os códigos 4xx indicam que o problema está na requisição enviada pelo cliente.

  • 400 Bad Request: JSON inválido ou campos obrigatórios ausentes
  • 401 Unauthorized: token ausente ou inválido
  • 403 Forbidden: usuário autenticado, mas sem permissão
  • 404 Not Found: endpoint ou recurso inexistente
  • 409 Conflict: conflito de estado (duplicidade ou concorrência)
  • 422 Unprocessable Entity: dados válidos, mas regra de negócio inválida
  • 429 Too Many Requests: limite de requisições excedido

Exemplo de erro padronizado:

{
  "error": "invalid_payload",
  "message": "Campo email é obrigatório",
  "status": 400
}

5xx — Status HTTP de Erros do Servidor

Os códigos 5xx indicam que o erro ocorreu dentro do servidor ou em sistemas intermediários.

  • 500 Internal Server Error: falha inesperada no backend
  • 502 Bad Gateway: proxy recebeu resposta inválida
  • 503 Service Unavailable: servidor em manutenção ou sobrecarga
  • 504 Gateway Timeout: backend demorou demais para responder

Como tratar status HTTP corretamente em APIs REST

Boas práticas fundamentais:

  • Não retorne 200 em erros: use códigos adequados
  • Padronize respostas de erro: JSON consistente facilita integração
  • Frontend deve mostrar mensagens claras: sem expor detalhes técnicos
  • Backend deve registrar logs completos: request_id e contexto

Tabela resumo dos principais status HTTP

Status Categoria Significado
200 Sucesso Requisição OK
201 Sucesso Recurso criado
204 Sucesso Sucesso sem corpo
400 Cliente Erro no payload
401 Cliente Não autenticado
403 Cliente Acesso proibido
404 Cliente Recurso inexistente
429 Cliente Rate limit excedido
500 Servidor Erro interno
503 Servidor Serviço indisponível

Dominar os status HTTP é uma habilidade essencial para qualquer desenvolvedor que trabalha com APIs REST. Uma API bem construída depende diretamente de códigos claros, respostas consistentes e tratamento correto de erros.