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:
- Aguarde o tempo de
Retry-Aftere 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. - 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.
- 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:
- IP Geolocation: Consultar um endereço IP e Consulta em lote
- Maps: O Maps não encontra nada: erros comuns
- Email Verifier: Verificar um endereço de e-mail
- YouTube: Canal não encontrado ou canal errado
- Processamento de mídia: Status e erros dos trabalhos de mídia
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.