Pular para o conteúdo principal

Padrões HTTP Status

Esta documentação visa definir os padrões de resposta que as nossas APIs utilizam. Seguimos as especificações globais do protocolo HTTP, garantindo que a integração com os nossos serviços seja previsível, eficiente e fácil de depurar.

🔹 Por que a padronização é importante?​

A utilização correta dos códigos de status HTTP não é apenas uma "boa prática", mas um pilar fundamental da arquitetura REST:

  • Interoperabilidade: Clientes HTTP, proxies e balanceadores de carga entendem estes códigos nativamente.
  • Facilidade de Debugging: Identificar a causa de um erro (ex: falta de permissão vs. recurso inexistente) acelera a análise com base apenas no código.
  • Cache e Performance: Muitos sistemas de cache decidem se devem armazenar uma resposta com base no código de status (ex: 200 é cacheável, já o 500 não é).
  • Redução de Suporte: APIs previsíveis geram menos dúvidas e chamados técnicos.

🔹 Categorias de Códigos​

As respostas são agrupadas em cinco classes, identificadas pelo primeiro dígito:

ClasseSignificadoDescrição
2xxSucessoA ação foi recebida, compreendida e aceita com sucesso.
3xxRedirecionamentoSão necessárias ações adicionais para completar o pedido.
4xxErro do ClienteO pedido contém sintaxe incorreta ou não pode ser processado devido a um erro do integrador.
5xxErro do ServidorO servidor falhou ao processar um pedido aparentemente válido.

🔹 Códigos mais utilizados na nossa API​

Sucesso (2xx)​

  • 200 OK: O pedido foi bem-sucedido. O corpo da resposta contém os dados solicitados.
  • 201 Created: O recurso foi criado com sucesso. Geralmente retornado após um POST.
  • 204 No Content: O pedido foi processado com sucesso, mas não há conteúdo para retornar (comum em DELETE ou PUT).

Erros do Cliente (4xx)​

  • 400 Bad Request: A requisição está malformada ou faltam campos obrigatórios.
  • 401 Unauthorized: Falha na autenticação. A API Key ou Token é inválido ou expirou.
  • 403 Forbidden: O cliente está autenticado, mas não tem permissão para acessar o recurso específico.
  • 404 Not Found: O recurso solicitado (ex: um sku de produto) não existe no servidor.
  • 422 Unprocessable Entity: A sintaxe está correta, mas existem erros semânticos (ex: falha na validação de regras de negócio).
  • 429 Too Many Requests: O limite de taxa (Rate Limit) foi excedido.

Erros do Servidor (5xx)​

  • 500 Internal Server Error: Ocorreu um erro inesperado do lado do servidor.
  • 503 Service Unavailable: O servidor está temporariamente em manutenção ou sobrecarregado.

🔹 Boas Práticas de Implementação​

  1. Não utilize apenas 200 OK: Evite retornar 200 OK com uma mensagem de erro no corpo ({ "error": true }). Isso confunde as ferramentas de monitorização e bibliotecas cliente.
  2. Idempotência: Garanta que pedidos GET, PUT e DELETE possam ser repetidos sem causar efeitos colaterais indesejados, mantendo a consistência dos códigos de retorno.
  3. Logs de Diagnóstico: Em caso de erros 5xx, forneça sempre um Request-ID no cabeçalho da resposta para facilitar o rastreio interno.