FlowData

O que significam as mensagens de erro das APIs do FlowData?

Publicado em 10. novembro 2026

Quando uma requisição ao FlowData falha, o status HTTP e o texto da resposta quase sempre revelam o motivo. Este artigo reúne as mensagens que são iguais em todas as áreas e mostra como reconhecer os erros de cada uma.

Verifique primeiro o status HTTP

As respostas de erro das áreas têm formatos diferentes. Por isso, faça sua integração confiar primeiro no status HTTP e só depois ler o texto:

Área Formato da resposta de erro
IP Geolocation {"status":"fail","message":"..."}
Maps {"success":false,"error":"...","details":{...}}
Email Verifier {"error":"Invalid email address"}
YouTube {"success":false,"error":"..."}
Processamento de mídia {"error":{"code":"...","message":"...","details":{...},"type":"..."}}

As mensagens de autenticação, acesso e cobrança abaixo são iguais em todas as áreas de dados. O processamento de mídia as retorna no próprio formato. Em https://api.flowdata.one/v1 você sempre recebe JSON. Um endereço desconhecido recebe 404 e um método errado, 405.

401: chave ausente ou inválida

O campo error vem sempre em alemão, por isso os valores abaixo aparecem exatamente como você os verá.

error Significado e solução
API-Token erforderlich Nenhuma chave foi recebida. Ela precisa estar no cabeçalho Authorization: Bearer fd_.... Outras formas, como um parâmetro na URL, não são consideradas, mesmo que o texto da mensagem cite um parâmetro "token". Verifique também se há exatamente um espaço entre Bearer e a chave.
Ungültiger API-Token A chave é desconhecida, expirou ou foi revogada. Verifique em Chaves de API se ela ainda está Ativa e se foi copiada por completo. Se você a renovou com Gerar novamente, o valor antigo vale só por pouco tempo.

Autenticações com falha não aparecem no registro, porque sem uma chave válida o FlowData não consegue identificar a equipe.

402: saldo ou limite insuficiente

Nas áreas de dados IP Geolocation, Maps, Email Verifier e YouTube, o FlowData responde com HTTP 402 quando a requisição não está coberta. A resposta tem este formato:

{"error":{"message":"...","type":"billing_error","code":"insufficient_quota"}}
code Significado e solução
insufficient_quota O saldo não é suficiente. Recarregue-o. Se sua equipe é cobrada conforme o uso, o limite de crédito foi esgotado; nesse caso, fale com o suporte.
spend_limit_exceeded O limite de gastos da equipe ou o limite dessa chave foi atingido no mês atual. Aumente-o ou aguarde o próximo mês.

Os trabalhos de mídia informam as mesmas causas com HTTP 429 e esses códigos, junto com o cabeçalho Retry-After.

Uma resposta 503 significa que a cobrança está indisponível por um instante. Tente novamente em breve.

403: acesso negado

code ou error Significado e solução
flowdata_access_denied A pessoa a quem a chave pertence perdeu o acesso ao FlowData. Devolva o acesso ou use outra chave.
Kein Teamzugriff A pessoa a quem a chave pertence não está mais na equipe. Crie uma nova chave.
insufficient_key_scope Você está usando a chave FlowData em um endpoint que não faz parte do FlowData, como o FlowCRM. Para isso, é preciso uma chave do seu perfil.
billing_suspended A cobrança do FlowData da sua equipe está suspensa. Fale com o suporte.
forbidden com flowdata_key_required em details Você está chamando o processamento de mídia com uma chave FlowSuite. Ele exige uma chave FlowData.

Saiba mais sobre os dois primeiros casos em Liberar o FlowData para a equipe e sobre o último em Substituir chaves FlowSuite.

429: muitas requisições

Cada chave pode enviar um número limitado de requisições por minuto. Ao atingir o limite, o FlowData responde com HTTP 429 até o minuto acabar. O cabeçalho Retry-After da resposta informa o tempo de espera em segundos. Veja como lidar com isso:

  1. Aguarde o tempo de Retry-After e repita a requisição. Se sua integração esperar um pouco mais a cada novo 429 antes de tentar de novo, normalmente o problema se resolve sozinho.
  2. Agrupe consultas quando puder. No IP Geolocation, uma consulta em lote com até 100 endereços conta como uma única requisição para esse limite. A cobrança, porém, é por entrada bem-sucedida.
  3. Guarde por pouco tempo no seu aplicativo os resultados que mudam raramente, em vez de consultá-los a cada visualização de página. No Maps, observe o aviso de uso na resposta (attribution), que não permite armazenamento permanente.

Outro 429 está ligado a autenticações com falha: se um endereço enviar muitas requisições com chave errada ou ausente em pouco tempo, o FlowData responde por um tempo com Zu viele fehlgeschlagene Authentifizierungsversuche. Corrija a chave e aguarde um momento.

O processamento de mídia permite 600 requisições e 60 novos trabalhos por minuto por chave. Outros limites estão em Iniciar um trabalho de mídia.

Erros de cada área

As mensagens sobre parâmetros, "não encontrado" e erros de servidor variam conforme a área. Você as encontra nestes artigos:

Bom saber

Todas as requisições com chave válida ficam no registro da respectiva área, incluindo as recusadas com 400, 402, 404, 422 ou 429. Coloque o filtro em Com falha e abra a resposta de erro exata pelo ícone de olho. Veja como em Estatísticas e registro de chamadas.

Este artigo foi útil?

Voltar para Primeiros passos e chaves de API