> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/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 da consulta e limites de taxa.

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

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>

Em caso de erro, a API retorna uma resposta com uma mensagem descritiva:

```json theme={null}
{
  "error": "Error message describing what went wrong"
}
```

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

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

<AccordionGroup>
  <Accordion title="Chave de serviço inválida">
    **Erro:** `Invalid service key`

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

  <Accordion title="Permissões insuficientes">
    **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 em Configurações da equipe
    * Consulte a [introdução à API](/pt-BR/desktop/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 consulta
</div>

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

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

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

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

    ```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 campo e de 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 do campo especificado.

    **Solução:** Consulte a seção [Campos disponíveis](/pt-BR/desktop/accounts/api-reference/custom-analytics#available-fields) para ver quais funções de agregação são válidas para cada campo. Campos de string normalmente aceitam apenas `COUNT` e `UNSPECIFIED`.
  </Accordion>

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

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

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

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

    **Causa:** 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
  </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 em uma requisiçã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">
  ## Limite de taxa
</div>

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

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

<div id="debugging-tips">
  ## Dicas de depuração
</div>

<div id="1-start-simple">
  ### 1. Comece pelo básico
</div>

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

```json theme={null}
{
  "service_key": "your_key",
  "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. Valide os nomes dos campos
</div>

Verifique novamente os nomes dos campos com a documentação de [Campos disponíveis](/pt-BR/desktop/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 selecionados.

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

Certifique-se de que seu JSON esteja formatado corretamente e que todas as strings estejam entre aspas corretamente.

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

Se você continuar enfrentando problemas:

1. **Verifique a mensagem de erro com atenção** - A maioria dos erros inclui orientações específicas sobre como corrigir o problema
2. **Revise os exemplos** - Compare a estrutura da sua consulta com os exemplos funcionais na documentação
3. **Entre em contato com o suporte** - Fale com o [Suporte do Devin Desktop](https://windsurf.com/support) e informe sua mensagem de erro específica e a consulta

<div id="api-version-notes">
  ## Observações 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 nas versões posteriores. Se você estiver usando uma versão mais antiga, considere atualizá-la para obter mensagens de erro mais detalhadas.