Tratamento de erros

Mensagens de erro comuns e dicas de depuração para a Analytics API, incluindo erros de autenticação, estrutura da consulta e limites de taxa.

​

Visão geral

Analytics API retorna mensagens de erro detalhadas para ajudar a depurar consultas inválidas. Esta página aborda cenários de erro comuns e como resolvê-los.

​

Formato da resposta de erro

Em caso de erro, a API retorna uma resposta com uma mensagem descritiva:

{
  "error": "Error message describing what went wrong"
}

​

Erros comuns

​

Erros de autenticação

Chave de serviço inválida

Erro: Invalid service key

Causa: A chave de serviço fornecida não é válida ou foi revogada.

Solução:

• Verifique se a chave de serviço está correta
• Verifique se a chave de serviço não foi revogada
• Gere uma nova chave de serviço, se necessário

Permissões insuficientes

Erro: Insufficient permissions

Causa: A chave de serviço não possui as permissões necessárias para o endpoint que você está chamando.

Solução:

• Atualize as permissões da chave de serviço em Configurações da equipe
• Consulte a introdução à API para ver a permissão específica exigida por cada endpoint

​

Erros na estrutura da consulta

Seleções ausentes

Erro: at least one field or aggregation is required

Causa: A requisição de consulta não contém nenhuma seleção nem agregação.

Solução: Adicione pelo menos uma seleção à sua requisição de consulta:

"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

Origem de dados inválida

Erro: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED

Causa: Provavelmente há um erro de digitação no campo data_source.

Solução: Confira novamente a grafia da sua origem de dados. Opções válidas:

• QUERY_DATA_SOURCE_USER_DATA
• QUERY_DATA_SOURCE_CHAT_DATA
• QUERY_DATA_SOURCE_COMMAND_DATA
• QUERY_DATA_SOURCE_PCW_DATA

Funções de agregação mistas

Erro: all selection fields should have an aggregation function, or none of them should

Causa: Algumas seleções têm funções de agregação, enquanto outras não.

Solução: Adicione funções de agregação a todas as seleções ou remova-as de todas elas:

Inválido:

"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]

Válido:

"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​

Erros de campo e de agregação

Função de agregação inválida

Erro: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM

Causa: A função de agregação não é compatível com o tipo do campo especificado.

Solução: Consulte a seção Campos disponíveis para ver quais funções de agregação são válidas para cada campo. Campos de string normalmente aceitam apenas COUNT e UNSPECIFIED.

Agregação em campo distinto

Erro: tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]

Causa: Campos com o padrão “distinct_*” não podem ser usados na seção de agregações.

Solução: Use os campos alternativos sugeridos para a agregação:

Inválido:

"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]

Válido:

"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]

Aliases de campo duplicados

Erro: duplicate field alias for selection/aggregation: num_acceptances

Causa: Várias seleções ou agregações têm o mesmo nome.

Solução: Certifique-se de que todos os aliases de campo sejam exclusivos. Lembre-se de que, se nenhum nome for especificado, o padrão será {aggregation_function}_{field_name}.

​

Erros de filtragem de dados

Nome do grupo inválido

Erro: invalid group name: GroupName

Causa: O nome de grupo especificado não existe na sua organização.

Solução:

• Confira novamente a grafia do nome do grupo
• Verifique se o grupo existe nas Configurações da equipe
• Use o nome exato do grupo, como ele aparece no painel da sua equipe

Formato de timestamp inválido

Erro: invalid timestamp format

Causa: O timestamp não está no formato RFC 3339 correto.

Solução: Use o formato de timestamp correto:

2023-01-01T00:00:00Z

Exemplos válidos:

• 2024-01-01T00:00:00Z
• 2024-12-31T23:59:59Z
• 2024-06-15T12:30:45Z

Filtros conflitantes

Erro: Cannot use both group_name and emails parameters

Causa: Os parâmetros group_name e emails foram fornecidos em uma requisição do Cascade Analytics.

Solução: Use group_name OU emails, mas não os dois:

Inválido:

{
  "group_name": "engineering",
  "emails": ["[e-mail]"]
}

Válido:

{
  "group_name": "engineering"
}

Ou:

{
  "emails": ["[e-mail]", "[e-mail]"]
}

​

Limite de taxa

Limite de taxa excedido

Erro: 429 Too Many Requests

Causa: Você excedeu o limite de taxa da API.

Solução:

• Aguarde antes de fazer requisições adicionais
• Implemente backoff exponencial no seu cliente
• Considere agrupar várias consultas em uma única requisição, sempre que possível
• Entre em contato com o suporte se precisar de limites de taxa mais altos

​

Dicas de depuração

​

1. Comece pelo básico

Comece com consultas básicas e vá adicionando complexidade aos poucos:

{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​

2. Valide os nomes dos campos

Verifique novamente os nomes dos campos com a documentação de Campos disponíveis.

​

3. Verifique a compatibilidade das agregações

Certifique-se de que suas funções de agregação sejam compatíveis com os tipos de campo selecionados.

​

4. Teste os filtros separadamente

Se a sua consulta não estiver retornando os resultados esperados, tente remover os filtros um a um para isolar o problema.

​

5. Use a formatação JSON adequada

Certifique-se de que seu JSON esteja formatado corretamente e que todas as strings estejam entre aspas corretamente.

​

Como obter ajuda

Se você continuar enfrentando problemas:

1. Verifique a mensagem de erro com atenção - A maioria dos erros inclui orientações específicas sobre como corrigir o problema
2. Revise os exemplos - Compare a estrutura da sua consulta com os exemplos funcionais na documentação
3. Entre em contato com o suporte - Fale com o Suporte do Devin Desktop e informe sua mensagem de erro específica e a consulta

​

Observações sobre a versão da API

O tratamento de erros e a validação foram aprimorados na versão 1.10.0 da API e nas versões posteriores. Se você estiver usando uma versão mais antiga, considere atualizá-la para obter mensagens de erro mais detalhadas.