> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tratamento de erros

> Mensagens de erro comuns e dicas de depuração para a Analytics API, incluindo erros de autenticação, estrutura de consultas e erros de limitação de taxa.

<div id="overview">
  ## Visão geral
</div>

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.

<div id="error-response-format">
  ## Formato de resposta de erro
</div>

Quando ocorre um erro, a API retorna uma resposta de erro com uma mensagem descritiva:

```json theme={null}
{
  "error": "Mensagem de erro descrevendo o que deu errado"
}
```

<div id="common-errors">
  ## Erros comuns
</div>

<div id="authentication-errors">
  ### Erros de autenticação
</div>

<AccordionGroup>
  <Accordion title="Invalid service key">
    **Erro:** `Invalid service key`

    **Causa:** 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
  </Accordion>

  <Accordion title="Insufficient permissions">
    **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 nas configurações da equipe
    * Consulte a [introdução à API](/pt-BR/windsurf/accounts/api-reference/api-introduction#required-permissions) para verificar a permissão específica exigida por cada endpoint
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Erros na Estrutura da Consulta
</div>

<AccordionGroup>
  <Accordion title="Selections ausentes">
    **Erro:** `at least one field or aggregation is required`

    **Causa:** 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:

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Fonte 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:** 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`
  </Accordion>

  <Accordion title="Funções de agregação mistas">
    **Erro:** `all selection fields should have an aggregation function, or none of them should`

    **Causa:** 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:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
      }
    ]
    ```

    **Válido:**

    ```json theme={null}
    "selections": [
      {
        "field": "num_acceptances",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      },
      {
        "field": "num_lines_accepted",
        "aggregation_function": "QUERY_AGGREGATION_SUM"
      }
    ]
    ```
  </Accordion>
</AccordionGroup>

<div id="field-and-aggregation-errors">
  ### Erros de campos e agregação
</div>

<AccordionGroup>
  <Accordion title="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 de campo especificado.

    **Solução:** Consulte a seção [Available Fields](/pt-BR/windsurf/accounts/api-reference/custom-analytics#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`.
  </Accordion>

  <Accordion title="Agregação em campo distinct">
    **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:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "distinct_developer_days",
        "name": "distinct_developer_days"
      }
    ]
    ```

    **Válido:**

    ```json theme={null}
    "aggregations": [
      {
        "field": "api_key",
        "name": "api_key"
      },
      {
        "field": "date",
        "name": "date"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Aliases de campo duplicados">
    **Erro:** `duplicate field alias for selection/aggregation: num_acceptances`

    **Causa:** 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}`.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Erros de filtragem de dados
</div>

<AccordionGroup>
  <Accordion title="Nome de grupo inválido">
    **Erro:** `invalid group name: GroupName`

    **Causa:** 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
  </Accordion>

  <Accordion title="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`
  </Accordion>

  <Accordion title="Filtros em conflito">
    **Erro:** `Cannot use both group_name and emails parameters`

    **Causa:** 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:**

    ```json theme={null}
    {
      "group_name": "engineering",
      "emails": ["user@example.com"]
    }
    ```

    **Válido:**

    ```json theme={null}
    {
      "group_name": "engineering"
    }
    ```

    **Ou:**

    ```json theme={null}
    {
      "emails": ["user@example.com", "user2@example.com"]
    }
    ```
  </Accordion>
</AccordionGroup>

<div id="rate-limiting">
  ## Limitação de taxa
</div>

<AccordionGroup>
  <Accordion title="Limite de taxa excedido">
    **Erro:** `429 Too Many Requests`

    **Causa:** 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
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Dicas de debugging
</div>

<div id="1-start-simple">
  ### 1. Comece de forma simples
</div>

Inicie com consultas básicas e, gradualmente, aumente a complexidade:

```json theme={null}
{
  "service_key": "sua_chave",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}
```

<div id="2-validate-field-names">
  ### 2. Validar nomes de campos
</div>

Confirme os nomes dos campos consultando a documentação de [Available Fields](/pt-BR/windsurf/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Verifique a compatibilidade das agregações
</div>

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

<div id="4-test-filters-separately">
  ### 4. Teste os filtros separadamente
</div>

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

<div id="5-use-proper-json-formatting">
  ### 5. Use a formatação JSON adequada
</div>

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

<div id="getting-help">
  ## Obtendo ajuda
</div>

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](https://windsurf.com/support) e inclua a mensagem de erro e a consulta específicas

<div id="api-version-notes">
  ## Notas da versão da API
</div>

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.