​
Troubleshooting

Use esta página quando uma chamada não funcionar como esperado.
Página focada em sintomas técnicos específicos (401/403, ambiente errado, PowerShell). Para um diagnóstico mais amplo, com cards por categoria e modelo de mensagem para pedir suporte, veja Erros comuns de integração.

Autenticação e ambiente

401/403, token de outro ambiente ou token que funciona em HML mas não em produção.

Status.code no corpo

HTTP 200 que na verdade é erro: status.code 400 ou 401 dentro do body.

cURL, código e PowerShell

Funciona no cURL mas não no seu código, ou o PowerShell quebra o comando.

Resposta sem o esperado

Sucesso sem dado, ou retorno que não é JSON (como o PDF do relatório).

​
Recebi 401 ou 403 (HTTP)

Em POST /api/service-api, um HTTP 401/403 de verdade só acontece por problema de autenticação: a chamada nem chega a processar o service.
  1. Token ausente.
  2. Token expirado.
  3. Token gerado em outro ambiente.
Como resolver:
  1. Gere um novo token.
  2. Confirme se a URL é de HML ou produção.
  3. Envie o header:
“Produto não liberado para a conta” e “service sem permissão” não geram HTTP 401/403 nesse endpoint. A chamada retorna HTTP 200 com o problema descrito em status.message (status.code 400 ou 401 dentro do corpo). Veja a seção seguinte.

​
HTTP 200, mas status.code diferente de 200

Esse é o caso mais comum de erro em POST /api/service-api: a chamada “funcionou” no sentido HTTP, mas o corpo mostra o problema real. Como resolver:
  1. Leia status.message.
  2. Confira se o body está em JSON válido.
  3. Confira se enviou Content-Type: application/json.
  4. Confira se o campo service está correto.
  5. Compare o body com o exemplo da API Reference.

​
O token funciona em HML, mas não em produção

Token e URL precisam ser do mesmo ambiente. Gere um token novo em produção usando credenciais de produção.

​
O cURL funciona, mas meu código não

Confira:
  1. URL base.
  2. Método HTTP.
  3. Headers.
  4. Body JSON.
  5. Timeout.
  6. Serialização do JSON.
  7. Header Authorization.
  8. Header Content-Type.
Compare o request do código com o request da API Reference.

​
O PowerShell quebra o comando cURL

No Windows, use curl.exe em vez de curl.
O comando curl sozinho pode ser interpretado pelo PowerShell como outro alias.

​
A consulta retornou sucesso, mas não veio o dado esperado

Nem todo retorno sem dado é erro técnico. Exemplos:
  1. certidão com “Nada consta”;
  2. CPF não encontrado em validação de endereço;
  3. pessoa não exposta politicamente;
  4. empresa sem débitos;
  5. lista vazia de relacionamentos.
Leia result e aplique a regra de negócio do seu produto.

​
A resposta não veio em JSON

Alguns endpoints retornam outro tipo de conteúdo. Exemplo:
Esse endpoint retorna PDF, não JSON.

​
Checklist rápido

Antes de pedir apoio, confira:
  1. A URL está correta?
  2. O método HTTP está correto?
  3. O token foi gerado no mesmo ambiente?
  4. O header Authorization foi enviado?
  5. O header Content-Type foi enviado?
  6. O body é JSON válido?
  7. O campo service está correto?
  8. O CPF/CNPJ está no campo esperado?
  9. O serviço está liberado para a conta?
  10. Você leu status.message?