Códigos de erro da API

Todo erro da API pública do Data Lead responde com um corpo JSON de um campo só:

{ "error": "Token ausente ou inválido" }

A mensagem é para pessoa, não para código: trate pelo status HTTP, nunca pelo texto.

Resumo

400 — Corpo ou parâmetro inválido

Acontece em cinco situações conhecidas:

O PATCH é estrito de propósito: um corpo com campo a mais é recusado, não ignorado. Aceitar em silêncio e gravar só parte deixaria o seu sistema e o Data Lead divergentes sem ninguém perceber.

Um ?cursor= corrompido nunca volta para a primeira página — repetir a página 1 em silêncio faria uma integração paginando em laço reprocessar os mesmos registros para sempre.

?limit= fora da faixa é recusado, não recortado. Pedir 500 e receber 200 OK com 200 registros faria a sua integração acreditar que recebeu a página que pediu, e o erro só apareceria depois, como registro faltando. Omitir o parâmetro continua valendo: sem ?limit= a página vem com 50.

401 — Token ausente ou inválido

{ "error": "Token ausente ou inválido" }

A resposta traz também WWW-Authenticate: Bearer.

A mesma mensagem cobre todos estes casos, de propósito — qualquer diferença entre eles viraria uma ferramenta para quem tenta adivinhar tokens:

• cabeçalho Authorization ausente ou fora do formato Bearer dl_…;
• token que não existe;
• token revogado;
• token vencido.

O que conferir, na ordem:

1. O cabeçalho está exatamente como Authorization: Bearer dl_…?
2. O token começa com dl_ e foi copiado inteiro?
3. Ele aparece na lista de Tokens da API em Configurações sem o selo Revogado?

Se o token foi revogado, não há como reativá-lo: gere outro.

403 — Token sem permissão

{ "error": "Token sem permissão para esta operação" }

Só acontece no PATCH /leads/{id}, a única escrita da API. O token foi criado com Somente leitura, e o escopo não muda depois da criação.

Solução: em Configurações → Tokens da API, gere um token novo com Leitura e escrita, troque na sua integração e revogue o antigo.

404 — Não encontrado

{ "error": "Não encontrado" }

O mesmo 404 responde a quatro situações: o registro não existe, o registro é de outra conta, o identificador não é um UUID válido, ou o caminho não existe (/api/v1/naoexiste, ou uma rota de uma versão antiga da especificação). A resposta é idêntica para que um identificador não vire oráculo de existência para quem varre a API com um token legítimo de outro cliente.

Um caminho desconhecido responde 404 em JSON, nunca um redirecionamento para a tela de login: esta é uma API servidor-a-servidor, e um cliente com redirecionamento automático ligado receberia o HTML do login e reportaria "JSON inválido" — um erro sem relação nenhuma com a causa real.

429 — Limite de requisições

{ "error": "Muitas requisições. Tente de novo em instantes." }

A resposta traz retry-after com quantos segundos esperar. Os limites são 120 requisições por minuto por token e 240 por minuto por IP de origem.

O que fazer:

• respeite o retry-after antes de repetir a chamada;
• aumente o ?limit= (até 200) em vez de fazer muitas chamadas pequenas;
• evite laços paralelos com o mesmo token.

500 — Erro interno

{ "error": "Erro interno. Tente novamente." }

O erro real fica no registro do servidor; a resposta é sempre essa frase fixa. Repita a chamada depois de alguns instantes. Se o erro se repetir, fale com o suporte informando a rota, o horário e o início do token.

Erros que não são da API

Duas confusões frequentes:

• A resposta não chega ao navegador. A API não devolve cabeçalhos de CORS. Chamá-la de uma página web falha no navegador mesmo com token válido — é intencional. Faça um proxy no seu servidor.
• A resposta parece "em cache". Ela não é: toda resposta das rotas autenticadas sai com cache-control: no-store, inclusive os erros. A exceção é GET /openapi.json, público e cacheável por uma hora — ele descreve a forma da API, não dados de ninguém. Se você está vendo dado velho, o cache é de algum proxy seu.

Boas práticas de integração

• Trate 429 e 500 com nova tentativa e espera crescente; trate 400, 401, 403 e 404 como erro de configuração, sem repetir em laço.
• Guarde o next_cursor e pare quando ele vier null.
• Não interprete o cursor: ele é opaco e pode mudar de formato sem aviso.

Veja também

• API pública — tokens, autenticação e limites
• Endpoints da API
• Webhooks

Precisa de ajuda?

Fale com o suporte da Data Stone pelo canal combinado com a sua conta. Tenha à mão a rota chamada, o status HTTP, o horário e o início do token (12 caracteres).