Erros comuns ao usar a API da Data Stone e como resolver

Visão geral

A API da Data Stone permite consultar, prospectar e enriquecer dados de pessoas físicas e jurídicas no Brasil. Com ela, é possível realizar consultas de pessoas e empresas, buscas avançadas, enriquecimento B2B em lote, validação de WhatsApp e acesso a dados auxiliares como CNAE, CBO e geolocalização.

Para usar a API corretamente, toda requisição deve ser enviada para a Base URL:

https://api.datastone.com.br/v1

Além disso, todas as chamadas precisam conter uma API Key válida no header Authorization.

Este artigo é direcionado para integrações via API da Data Stone e contém informações técnicas sobre a implementação e configuração.
Caso precise de ajuda, entre em contato com nosso time pelo chat disponível na plataforma.

1. Antes de integrar: o que você precisa conferir

Antes de testar qualquer endpoint, valide estes quatro pontos:

1. Você está usando a Base URL correta.

2. A sua requisição possui o header Authorization.

3. A API Key foi copiada no formato correto.

4. O IP usado para fazer a requisição está liberado na whitelist, quando aplicável.

Esses pontos são importantes para garantir o funcionamento correto da integração. Antes de iniciar testes em endpoints mais avançados, recomendamos validar itens como autenticação, preenchimento dos headers, API Key utilizada e liberação do IP na whitelist, pois eles são pré-requisitos para o acesso à API.

2. Como funciona a autenticação

Todas as requisições precisam enviar a API Key no header Authorization.

O formato obrigatório é:

Authorization: Token sua-api-key

Exemplo em cURL:

curl -H "Authorization: Token sua-api-key" https://api.datastone.com.br/v1/balance

Dependendo da ferramenta usada, a diferença de maiúsculas/minúsculas pode causar comportamento inesperado. Use sempre Authorization.

3. Erro 401: API Key inválida

Esse erro é retornado quando a autenticação da requisição não é validada corretamente. As causas mais comuns são API Key inválida ou inconsistências na estrutura do header enviado na requisição.

Exemplo de retorno:

{
  "detail": "Verifique o token informado."
}

Como resolver

Confira se:

1. A API Key foi copiada por completo;

2. Não existem espaços antes ou depois da chave;

3. O header está exatamente no formato descrito no ponto anterior;

4. A chave ainda está ativa no painel;

5. Se necessário, gere uma nova API Key.

Diagnóstico rápido

Teste primeiro o endpoint de saldo. Ele é simples e ajuda a validar se o problema é autenticação antes de investigar filtros, payloads ou regras de negócio.

curl -H "Authorization: Token sua-api-key" https://api.datastone.com.br/v1/balance

4. Como funciona a whitelist de IPs

A whitelist é uma lista de IPs autorizados a acessar a API da empresa.

Na prática, ela funciona como uma camada de segurança: mesmo que a API Key esteja correta, a requisição pode ser bloqueada caso venha de um IP que não está autorizado.

Quando isso acontece, a API retorna erro 401 - IP Não Autorizado. Para resolver, copie o IP exibido na mensagem de erro e adicione esse IP em Meu Perfil > Whitelist de IPs.

Exemplo de erro:

{
  "detail": "Acesso não autorizado. O IP 192.168.1.1 não está na lista de IPs permitidos. Adicione este IP na whitelist da sua empresa para liberar o acesso."
}

Como resolver

1. Copie o IP exibido na mensagem de erro;

2. Na sua conta Data Stone, clique no nome da sua empresa, no canto superior direito;

3. Clique em Configurações da Conta;

4. Vá em Meu Perfil > Configurações de Limites> Whitelist de IPs;

5. Adicione o IP informado;

6. Aguarde alguns segundos;

7. Tente executar a requisição novamente.

5. Por que meu IP muda?

O IP de origem de uma requisição pode variar conforme o ambiente utilizado para realizar a chamada da API.

A API identifica o endereço IP público da origem da requisição, que pode corresponder a um servidor, ferramenta de automação, aplicação ou ambiente local utilizado na integração.

Por isso, uma mesma API Key pode funcionar corretamente em um ambiente e apresentar bloqueio em outro caso o IP utilizado não esteja liberado na whitelist.

Exemplos:

Uma mesma integração pode funcionar em um ambiente e falhar em outro mesmo utilizando a mesma API Key, devido à diferença no IP de saída.

6. Whitelist de IPs: o que ela resolve e o que ela não resolve

A whitelist de IPs permite autorizar chamadas realizadas a partir de endereços IP específicos.

Esse controle é utilizado para restringir e validar a origem das requisições feitas à API e, em alguns cenários, também pode evitar bloqueios relacionados ao limite diário de requisições, conforme a configuração aplicada na conta.

No entanto, a whitelist não altera outras regras de utilização da API, como:

• Saldo de créditos;

• Limite mensal do produto;

• Permissão de acesso a endpoints não contratados;

• Dados retornados pela API.

Ou seja, a liberação de IP atua apenas no controle de acesso da requisição. Caso a conta esteja sem créditos ou sem permissão para determinado recurso, a chamada continuará sendo bloqueada.

7. Erro 400: saldo insuficiente

Esse erro acontece quando a conta não possui créditos suficientes para executar a operação.

Exemplo de retorno:

{
  "error": {
    "code": "no credits",
    "description": "Você não possui saldo suficiente, disponível 0"
  }
}

Como resolver

Verifique o saldo disponível no painel da plataforma ou pelo endpoint de consulta de saldo.

Caso o saldo esteja zerado ou insuficiente, será necessário adquirir mais créditos ou entrar em contato com o suporte.

8. Erro 429: limite de requisições excedido

O erro 429 acontece quando o limite de requisições foi excedido.

A plataforma possui limites de utilização compartilhados entre API e painel, além de limites mensais por produto. Atualmente, os limites padrão são:

• 100 requisições por dia

• 100.000 requisições/mês para produtos B2C

• 50.000 requisições/mês para produtos B2B

Exemplo de retorno:

{
  "detail": "O limite de utilização por usuário foi excedido. Contate o seu administrador para aumentar ou aguarde o reinício do ciclo no próximo mês."
}

Como resolver

1. Aguarde o reinício do ciclo de utilização;

2. Solicite aumento de limite ao administrador da conta;

3. Verifique se o IP utilizado deve ser liberado na whitelist;

4. Revise automações e integrações para evitar chamadas repetidas ou desnecessárias.

Atenção para automações

O limite pode ser atingido por requisições diretas da API ou por automações que executam chamadas em excesso.

Fluxos automatizados utilizando ferramentas como n8n, Make, Zapier, scripts em loop ou agentes de IA podem gerar um volume elevado de requisições em pouco tempo caso não exista controle de execução.

Recomendamos validar condições de disparo, limites de repetição, tratamentos de erro e intervalos entre chamadas para evitar consumo excessivo da API.

9. Diferença entre limite de requisição e limite de produto

Existem dois tipos de limite que podem resultar no retorno do erro 429.

Limite de requisições

O limite de requisições controla a quantidade de chamadas realizadas em determinado período.

Atualmente, o limite padrão informado na documentação é de 100 requisições por dia, compartilhado entre utilização da API e acesso ao painel da plataforma.

Limite de produto

O limite de produto corresponde ao volume mensal de utilização permitido para cada tipo de produto contratado.

Em resumo

• O limite de requisições controla quantas chamadas podem ser realizadas em um período específico;

• O limite de produto controla o volume total de utilização permitido no mês;

• Ambos os limites podem resultar em erro 429 quando excedidos.

10. Cuidados com webhooks

Os webhooks são utilizados para notificar automaticamente o sistema do cliente ao final de processos como enriquecimento ou prospecção.

Quando o processamento é concluído, a API envia uma requisição POST para a URL configurada, contendo informações como job_id, job_type e status.

Exemplo de payload:

{
  "job_id": 123,
  "job_type": "enrichment",
  "status": "done"
}

A URL configurada deve retornar um HTTP 200 imediatamente após o recebimento da requisição.

O envio do webhook possui:

• Até 3 tentativas de entrega;

• Intervalo de 1 minuto entre tentativas;

• Timeout de 30 segundos por requisição.

Erros comuns com webhook

Para evitar falhas no recebimento dos eventos, recomendamos evitar:

1. Utilizar URLs com tempo elevado de resposta;

2. Retornar códigos diferentes de HTTP 200;

3. Executar toda a lógica de processamento antes da resposta da requisição;

4. Configurar URLs locais, como localhost;

5. Bloquear chamadas externas via firewall ou regras de rede;

6. Exigir autenticação sem configurar corretamente o recebimento do webhook.

Melhor prática

O ideal é que o endpoint do webhook responda rapidamente à requisição.

Recomendamos receber o payload, registrar as informações necessárias e retornar HTTP 200 imediatamente. O processamento adicional pode ser executado posteriormente em segundo plano pelo sistema.

11. Cuidados com filtros e parâmetros

Alguns endpoints exigem o envio de valores específicos nos filtros, e não apenas os textos exibidos na interface.

Em filtros que possuem diferenciação entre texto e valor, deve ser enviado o valor esperado pela API. Por exemplo, no filtro de estado, o formato correto é a sigla da UF.

Correto:

{
  "estado": "SP"
}

Incorreto:

{
  "estado": "São Paulo"
}

Também existem endpoints auxiliares utilizados para consulta de valores válidos em filtros, como:

• Cidades

• CBO

• CNAE

• Setores CNAE

Nesses casos, o valor retornado no campo code deve ser utilizado nas requisições de prospecção e consulta.

Sempre que existir um endpoint auxiliar, autocomplete ou retorno estruturado de valores, utilize os identificadores retornados pela própria API nas requisições seguintes.

12. Cuidado com campos formatados

Alguns endpoints exigem que determinados campos sejam enviados sem máscara ou caracteres de formatação.

Exemplos:

CNPJ

Para consultar empresa por CNPJ, o parâmetro cnpj deve ser enviado apenas com números.

Correto:

12345678000199

Incorreto:

12.345.678/0001-99

WhatsApp

Na validação de WhatsApp, a documentação informa que os campos ddd e phone devem ser enviados separadamente e sem formatação, sem traços ou espaços.

Correto:

{
  "ddd": "11",
  "phone": "999999999"
}

Incorreto:

{
  "phone": "(11) 99999-9999"
}

Sempre valide o formato esperado de cada campo antes de enviar a requisição. Campos com máscaras, caracteres especiais ou estrutura diferente da esperada podem resultar em falha na validação ou retorno incorreto da API.

13. Cuidado com processos assíncronos

Algumas operações não retornam o resultado final imediatamente. Em vez disso, elas iniciam um processamento em segundo plano, e o resultado é disponibilizado posteriormente via webhook ou por meio de endpoints de consulta.

Isso ocorre em fluxos como enriquecimento e prospecção, onde o processamento pode levar algum tempo para ser concluído. Nesses casos, o status de conclusão pode ser enviado via webhook, e os resultados também podem ser consultados posteriormente em endpoints específicos.

A resposta inicial da requisição indica apenas o início do processamento. O resultado final é disponibilizado após a conclusão.

Como o fluxo funciona na prática

1. Você realiza a solicitação;

2. A API retorna um identificador do processo (job);

3. O processamento ocorre em segundo plano;

4. O resultado fica disponível após a conclusão;

5. O webhook pode notificar quando o processo for finalizado.

14. Checklist antes de abrir chamado

Antes de acionar o suporte, valide:

Estou usando a Base URL correta?
Estou usando o endpoint correto?
Enviei o header Authorization?
O header está no formato Authorization: Token minha-chave?
Copiei a API Key sem espaços extras?
O IP que está fazendo a chamada está na whitelist?
Estou usando o IP real da ferramenta ou servidor, e não apenas o IP do meu computador?
A conta tem saldo suficiente?
O limite diário ou mensal foi excedido?
O payload está no formato esperado?
Estou enviando CNPJ, CPF, DDD e telefone sem máscara quando necessário?
Para filtros, estou usando o valor correto retornado pela API?
Se for webhook, minha URL responde HTTP 200 rapidamente?
Se for processo assíncrono, estou aguardando o processamento finalizar?

15. Exemplos rápidos de diagnóstico

Quero saber se minha API Key funciona

Teste a autenticação com a requisição abaixo:

curl -H "Authorization: Token sua-api-key" https://api.datastone.com.br/v1/balance

Se o retorno for 401, revise a API Key e o formato do header utilizado.

A API Key está correta, mas recebo erro de IP não autorizado

Verifique qual IP está sendo utilizado na requisição e adicione esse endereço na Whitelist de IPs.

Após a liberação, aguarde alguns segundos e teste novamente.

Funcionou no Postman, mas não funciona no n8n

Nesse cenário, o mais comum é diferença no IP de saída.

O Postman geralmente utiliza a rede local do usuário, enquanto o n8n pode estar rodando em outro ambiente (servidor ou cloud), com um IP diferente.

Adicione o IP de saída do ambiente do n8n na whitelist.

Estou recebendo erro 429

Esse erro indica que algum limite de uso foi atingido.

Verifique se você excedeu:

• limite diário de requisições;

• limite mensal do produto;

• volume de chamadas gerado por automações ou loops.

O webhook não recebe o resultado

Valide se o endpoint configurado:

• é público e acessível externamente;

• aceita requisições POST;

• retorna HTTP 200 rapidamente;

• não bloqueia chamadas externas por firewall ou regras de rede;

• não executa processamento pesado antes de responder.

Documentação completa da API

Para detalhes técnicos adicionais, endpoints disponíveis e especificações atualizadas, acesse a documentação oficial da API.

https://api.datastone.com.br/docs