Guia de erros de API: como identificar e resolver (400 vs 500)

Ao integrar com as APIs da Logcomex (LogManager, NCM Intel, Shipment Intel, etc.), a resposta mais importante para o seu diagnóstico é o HTTP Status Code.

Antes de abrir um chamado, verifique o código recebido para entender se a ação necessária está do seu lado (cliente) ou do nosso (servidor).

1. Erros do cliente (4xx) - Ação necessária: correção no seu código

Esses erros indicam que a requisição enviada possui algum problema de formato, autenticação ou dados. O servidor rejeitou o pedido.

400 Bad Request (sintaxe inválida)
- O que significa: O JSON enviado está mal formatado (vírgula sobrando, aspas faltando) ou você enviou um tipo de dado errado (ex: enviou texto num campo que exige número).
- Como resolver: Valide seu JSON em um Linter. Verifique na documentação se os campos obrigatórios foram preenchidos e se os tipos de dados (String, Integer, Boolean) estão corretos.
401 Unauthorized (falha de autenticação)
- O que significa: O sistema não reconheceu quem você é. Geralmente problemas com a API Key ou Token.
- Como resolver:
  - Verifique se o header x-api-key ou Authorization está escrito corretamente.
  - Confira se não há espaços em branco antes ou depois da chave.
  - Confirme se sua chave ainda está ativa com seu Gerente de Contas.
404 Not Found (não encontrado)
- O que significa: O Endpoint (URL) está errado ou o ID do recurso que você tentou buscar não existe.
- Como resolver: Verifique a grafia da URL na documentação oficial. Se for uma busca por ID (ex: buscar um container específico), confirme se esse ID realmente existe na base.
429 Too Many Requests (bloqueio por volume)
- O que significa: Você ultrapassou o limite de requisições por mês do seu plano.
- Como resolver: Implemente uma lógica de backoff (espera) no seu código. Aguarde alguns segundos antes de tentar novamente.

2. Erros do servidor (5xx) - Ação necessária: aguardar ou reportar

Esses erros indicam que sua requisição chegou corretamente, mas o servidor da Logcomex (ou uma fonte externa) falhou ao processá-la.

500 Internal Server Error / 502 Bad Gateway
- O que significa: Falha interna ou instabilidade momentânea.
- Cenário comum na Logística: Muitas de nossas APIs consultam fontes governamentais em tempo real (Portal Único, Mercante, Sefaz). Se esses portais estiverem instáveis ou fora do ar, nossa API retornará erro 5xx.
- Como resolver:
  1. Aguarde 5 a 10 minutos e faça uma nova tentativa (Retry).
  2. Se o erro persistir por mais de 1 hora, abra um chamado no suporte via chat.
504 Gateway Timeout
- O que significa: A fonte de dados demorou muito para responder e a conexão expirou.
- Como resolver: Aguarde e tente novamente mais tarde.

3. Como reportar um erro ao suporte?

Se você identificou um erro persistente ou bug, envie as informações abaixo via chat para agilizar a análise técnica (sem esses dados, o tempo de resolução aumenta):

Endpoint completo: (Ex: POST https://api-prd-logmanager.logcomex.io/api/v1/search)
O Payload (Body) enviado: (O JSON exato que você enviou).
A resposta de erro completa: (O código e a mensagem JSON que a API devolveu).
Horário da tentativa: Data e hora exata.