​
Visão geral

A 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

Quando ocorre um erro, a API retorna uma resposta de erro com uma mensagem descritiva: 
{
  "error": "Mensagem de erro descrevendo o que deu errado"
}

​
Erros comuns

​
Erros de autenticação

Erro: Invalid service keyCausa: A Service Key fornecida não é válida ou foi revogada.Solução:
  • Verifique se sua Service Key está correta
  • Confira se a Service Key não foi revogada
  • Gere uma nova Service Key, se necessário
Erro: Insufficient permissionsCausa: A Service Key não possui as permissões necessárias “Teams somente leitura”.Solução:
  • Atualize as permissões da Service Key nas configurações da equipe
  • Certifique-se de que a Service Key tenha acesso “Teams somente leitura”

​
Erros na estrutura da query

Erro: at least one field or aggregation is requiredCausa: A solicitação da query não contém nenhuma selections ou aggregations.Solução: Adicione pelo menos uma selection à solicitação da sua query:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Erro: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCausa: Provavelmente há um erro de digitação no campo data_source.Solução: Verifique a grafia da sua data source. Opções válidas:
  • QUERY_DATA_SOURCE_USER_DATA
  • QUERY_DATA_SOURCE_CHAT_DATA
  • QUERY_DATA_SOURCE_COMMAND_DATA
  • QUERY_DATA_SOURCE_PCW_DATA
Erro: all selection fields should have an aggregation function, or none of them shouldCausa: Algumas selections têm funções de agregação enquanto outras não.Solução: Adicione funções de agregação a todas as selections ou remova de todas: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 campos e agregações

Erro: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCausa: A função de agregação não é compatível com o tipo de campo especificado.Solução: Consulte a seção Available Fields para ver quais funções de agregação são válidas para cada campo. Campos do tipo string geralmente oferecem suporte apenas a COUNT e UNSPECIFIED.
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 aggregations.Solução: Use os campos alternativos sugeridos para 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"
  }
]
Erro: duplicate field alias for selection/aggregation: num_acceptancesCausa: Múltiplas selections ou aggregations têm o mesmo nome.Solução: Garanta que todos os aliases de campo sejam únicos. Lembre-se de que, se nenhum nome for especificado, o padrão é {aggregation_function}_{field_name}.

​
Erros de filtragem de dados

Erro: invalid group name: GroupNameCausa: O nome do grupo especificado não existe na sua organização.Solução:
  • Confira a grafia do nome do grupo
  • Verifique se o grupo existe nas configurações da sua equipe
  • Use exatamente o nome do grupo como aparece no painel da sua equipe
Erro: invalid timestamp formatCausa: 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
Erro: Cannot use both group_name and emails parametersCausa: Os parâmetros group_name e emails foram fornecidos simultaneamente em uma solicitação do Cascade Analytics.Solução: Use group_name OU emails, mas não os dois:Inválido:
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
Válido:
{
  "group_name": "engineering"
}
Ou:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Limitação de taxa

Erro: 429 Too Many RequestsCausa: Você excedeu o limite de requisições da API.Solução:
  • Aguarde antes de fazer novas requisições
  • Implemente backoff exponencial no seu cliente
  • Considere agrupar várias consultas em uma única requisição, quando possível
  • Entre em contato com o suporte se precisar de limites de taxa mais altos

​
Dicas de Debug

​
1. Comece de forma simples

Comece com consultas básicas e vá adicionando complexidade aos poucos: 
{
  "service_key": "sua_chave",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. Validar nomes de campos

Verifique os nomes dos campos na 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 que você está selecionando.

​
4. Teste os filtros separadamente

Se 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 correta

Garanta que seu JSON esteja corretamente formatado e que todas as strings estejam corretamente entre aspas.

​
Obtendo ajuda

Se você continuar enfrentando problemas:
  1. Verifique atentamente a mensagem de erro - A maioria das mensagens inclui orientações específicas sobre como corrigir o problema
  2. Revise os exemplos - Compare a estrutura da sua consulta com os exemplos que funcionam na documentação
  3. Fale com o suporte - Entre em contato com o Windsurf Support e envie a mensagem de erro e a consulta específicas

​
Notas 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 posteriores. Se você estiver usando uma versão mais antiga, considere atualizar para obter mensagens de erro mais detalhadas.