> ## 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 de requisições.

<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 da 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="Service Key inválida">
    **Erro:** `Invalid service key`

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

  <Accordion title="Permissões insuficientes">
    **Erro:** `Insufficient permissions`

    **Causa:** A Service Key não possui as permissões necessárias para o endpoint que você está usando.

    **Solução:**

    * Atualize as permissões da Service Key nas configurações da equipe
    * Consulte a [introdução à API](/pt-BR/plugins/accounts/api-reference/api-introduction#required-permissions) para ver a permissão específica exigida por cada endpoint
  </Accordion>
</AccordionGroup>

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

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

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

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

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

  <Accordion title="Funções de agregação inconsistentes">
    **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ções
</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/plugins/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 oferecem suporte apenas 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 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 campos 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 é `{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 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
  </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 conflitantes">
    **Erro:** `Cannot use both group_name and emails parameters`

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

    ```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ê 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
  </Accordion>
</AccordionGroup>

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

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

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

```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>

Verifique os nomes dos campos na documentação de [Campos disponíveis](/pt-BR/plugins/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 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 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 correta
</div>

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

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

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

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

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.