---
title: "Erros comuns ao usar a API da Data Stone e como resolver"
description: "Entenda os principais erros ao integrar com a API da Data Stone, como autenticação, whitelist de IPs, limites de requisição, saldo insuficiente e webhooks."
url: https://suporte.datastone.com.br/pt-br/articles/11385771-erros-comuns-ao-usar-a-api-da-data-stone-e-como-resolver
collection: "API"
updated: 2026-11-10
language: pt-br
---

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

Entenda os principais erros ao integrar com a API da Data Stone, como autenticação, whitelist de IPs, limites de requisição, saldo insuficiente e webhooks.

## 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:

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

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

> **Warning:** 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 é:

```javascript
Authorization: Token sua-api-key
```

Exemplo em cURL:

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

> **Info:** 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:

```javascript
{
  "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.

```javascript
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:

```javascript
{
  "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:

<table data-id="6a0de302-98d5-4733-a0d2-dd2cab838875" style="min-width: 50px;"><colgroup><col style="min-width: 25px;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="b3cdc661-e705-4c41-8e53-5f67004c720a"><strong>Onde a requisição é feita</strong></p></td><td colspan="1" rowspan="1"><p data-id="fff311e2-ee0b-4489-ab32-52ae4b211dbe"><strong>IP identificado pela API</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="7ea57b48-c5ef-4a26-a00c-6f8ec9e788f4">Seu computador</p></td><td colspan="1" rowspan="1"><p data-id="4a055c14-6c97-4a35-82c8-1c8bbde31aae">IP da sua rede atual</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="0b062748-ff32-43e5-8890-92ca1e5e0452">Servidor da empresa</p></td><td colspan="1" rowspan="1"><p data-id="b9b56495-f555-4df6-a239-1f6742deb7e2">IP público do servidor</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="611a69b5-5aab-4282-b77a-caaf40e47eca">n8n em nuvem</p></td><td colspan="1" rowspan="1"><p data-id="326deb06-0f03-4934-9a3d-9a1c7417d239">IP de saída do ambiente do n8n</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="3b5e498f-6db1-4155-8600-caa682acc808">Make, Zapier ou outra automação</p></td><td colspan="1" rowspan="1"><p data-id="d0017508-2f19-4b66-9e0a-f34f28a2f8d6">IP de saída da plataforma usada</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="592f8162-535b-4e42-a098-6ba2b52d022d">Aplicação em cloud</p></td><td colspan="1" rowspan="1"><p data-id="e44212ff-6f7f-4171-8384-8f747ff97a28">IP público da infraestrutura cloud</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="d7c10943-01af-476d-9d85-a772639ba60c">VPN ativa</p></td><td colspan="1" rowspan="1"><p data-id="0eacef26-98b4-4ae9-a3a2-aa9adc51bc02">IP da VPN</p></td></tr></tbody></table>

> **Info:** 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:

```javascript
{
  "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:

```javascript
{
  "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

> **Warning:** 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.

<table data-id="03be11ac-283f-481e-ab5a-335f891e4383" style="min-width: 385px;"><colgroup><col style="width: 50.85%;"><col style="min-width: 25px;"></colgroup><tbody><tr><td colspan="1" rowspan="1"><p data-id="5ba3e9cf-7ac0-4d69-85a5-9002c53f942d"><strong>Produto</strong></p></td><td colspan="1" rowspan="1"><p data-id="aa35a73c-9b8f-42e5-85e7-43231a39c05a"><strong>Limite mensal</strong></p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="79c4d46d-6c3b-4346-bf62-c6724c103313">B2C, incluindo Consulta, Enriquecimento e Prospecção</p></td><td colspan="1" rowspan="1"><p data-id="f9df9a4b-1029-4129-b99f-dff1221e4a0b">100.000 requisições/mês</p></td></tr><tr><td colspan="1" rowspan="1"><p data-id="da4c89a3-3e2a-4009-bf5d-009e6ecdd9bc">B2B, incluindo Prospecção B2B e Consulta B2B</p></td><td colspan="1" rowspan="1"><p data-id="84414130-a0a8-42fd-9a5b-314db2079317">50.000 requisições/mês</p></td></tr></tbody></table>

### 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:

```javascript
{
  "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:

```javascript
{
  "estado": "SP"
}
```

Incorreto:

```javascript
{
  "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.

> **Info:** 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:

```javascript
12345678000199
```

Incorreto:

```javascript
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:

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

Incorreto:

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

> **Info:** 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.

> **Warning:** 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:

```javascript
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](https://api.datastone.com.br/docs)
