​
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 de 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 Chave de serviço fornecida não é válida ou foi revogada.Solução:
  • Verifique se sua Chave de serviço está correta
  • Confira se a Chave de serviço não foi revogada
  • Gere uma nova Chave de serviço, se necessário
Erro: Insufficient permissionsCausa: A Chave de serviço não possui as permissões “Teams Read-only” necessárias.Solução:
  • Atualize as permissões da Chave de serviço nas configurações da equipe
  • Garanta que a Chave de serviço tenha acesso “Teams Read-only”

​
Erros na Estrutura da Consulta

Erro: at least one field or aggregation is requiredCausa: A solicitação de consulta não contém nenhuma selections ou aggregations.Solução: Adicione pelo menos uma selection à sua solicitação de consulta:
"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 fonte 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
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ção

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 só têm suporte 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 de 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 será {aggregation_function}_{field_name}.

​
Erros de filtragem de dados

Erro: invalid group name: GroupNameCausa: O nome de grupo especificado não existe na sua organização.Solução:
  • Verifique a grafia do nome do grupo
  • Confira se o grupo existe nas configurações da sua equipe
  • Use o nome exato do grupo conforme 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 juntos em uma solicitação do Cascade Analytics.Solução: Use group_name OU emails, mas não ambos: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ê ultrapassou o limite de taxa da API.Solução:
  • Aguarde antes de fazer novas solicitações
  • Implemente backoff exponencial no cliente
  • Considere agrupar várias consultas em uma única solicitação quando possível
  • Contate o suporte se precisar de limites de taxa mais altos

​
Dicas de debugging

​
1. Comece de forma simples

Inicie com consultas básicas e, gradualmente, aumente a complexidade: 
{
  "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

Confirme os nomes dos campos consultando a documentação de Available Fields.

​
3. Verifique a compatibilidade das agregações

Certifique-se de que as suas funções de agregação sejam compatíveis com os tipos de campo que você está selecionando.

​
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

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

​
Obtendo ajuda

Se você continuar tendo problemas:
  1. Verifique a mensagem de erro com atenção - A maioria dos erros traz 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. Contate o suporte - Entre em contato com o Windsurf Support e inclua a mensagem de erro e a consulta específicas

​
Notas da versão da API

O tratamento de erros e a validação foram aprimorados na API a partir da versão 1.10.0. Se você estiver usando uma versão anterior, considere atualizar para obter mensagens de erro mais detalhadas.