Tratamento de erros

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 keyCausa: 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 permissionsCausa: 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 requiredCausa: 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_UNSPECIFIEDCausa: 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 shouldCausa: 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_SUMCausa: 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_acceptancesCausa: 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: GroupNameCausa: 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 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

Filtros conflitantes

Erro: Cannot use both group_name and emails parametersCausa: 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": ["user@example.com"]
}

Válido:

{
  "group_name": "engineering"
}

Ou:

{
  "emails": ["user@example.com", "user2@example.com"]
}

Limite de taxa

Limite de taxa excedido

Erro: 429 Too Many RequestsCausa: 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:

Verifique a mensagem de erro com atenção - A maioria dos erros inclui orientações específicas sobre como corrigir o problema
Revise os exemplos - Compare a estrutura da sua consulta com os exemplos funcionais na documentação
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.

Devin Desktop

Central de Comando do Agente

Lançamentos

Plugins do Windsurf

Contas

Segurança

Visão geral

Formato da resposta de erro

Erros comuns

Erros de autenticação

Erros na estrutura da consulta

Erros de campo e de agregação

Erros de filtragem de dados

Limite de taxa

Dicas de depuração

1. Comece pelo básico

2. Valide os nomes dos campos

3. Verifique a compatibilidade das agregações

4. Teste os filtros separadamente

5. Use a formatação JSON adequada

Como obter ajuda

Observações sobre a versão da API

​Visão geral

​Formato da resposta de erro

​Erros comuns

​Erros de autenticação

​Erros na estrutura da consulta

​Erros de campo e de agregação

​Erros de filtragem de dados

​Limite de taxa

​Dicas de depuração

​1. Comece pelo básico

​2. Valide os nomes dos campos

​3. Verifique a compatibilidade das agregações

​4. Teste os filtros separadamente

​5. Use a formatação JSON adequada

​Como obter ajuda

​Observações sobre a versão da API

Visão geral

Formato da resposta de erro

Erros comuns

Erros de autenticação

Erros na estrutura da consulta

Erros de campo e de agregação

Erros de filtragem de dados

Limite de taxa

Dicas de depuração

1. Comece pelo básico

2. Valide os nomes dos campos

3. Verifique a compatibilidade das agregações

4. Teste os filtros separadamente

5. Use a formatação JSON adequada

Como obter ajuda

Observações sobre a versão da API