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

# Gestione degli errori

> Messaggi di errore comuni e suggerimenti di debug per l'API di analisi, inclusi errori di autenticazione, struttura delle query e limitazione della frequenza delle richieste.

<div id="overview">
  ## Panoramica
</div>

L'API di analisi restituisce messaggi di errore dettagliati per agevolare il debug delle query non valide. Questa pagina descrive gli scenari di errore più comuni e come risolvere questi problemi.

<div id="error-response-format">
  ## Formato della risposta d'errore
</div>

Quando si verifica un errore, l'API restituisce una risposta d'errore con un messaggio descrittivo:

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

<div id="common-errors">
  ## Errori comuni
</div>

<div id="authentication-errors">
  ### Errori di autenticazione
</div>

<AccordionGroup>
  <Accordion title="Chiave di servizio non valida">
    **Errore:** `Invalid service key`

    **Causa:** La chiave di servizio fornita non è valida o è stata revocata.

    **Soluzione:**

    * Verifica che la chiave di servizio sia corretta
    * Verifica che la chiave di servizio non sia stata revocata
    * Genera una nuova chiave di servizio, se necessario
  </Accordion>

  <Accordion title="Autorizzazioni insufficienti">
    **Errore:** `Insufficient permissions`

    **Causa:** La chiave di servizio non dispone delle autorizzazioni richieste per l'endpoint che stai chiamando.

    **Soluzione:**

    * Aggiorna le autorizzazioni della chiave di servizio in impostazioni del team
    * Consulta l'[introduzione alle API](/it/desktop/accounts/api-reference/api-introduction#required-permissions) per l'autorizzazione specifica richiesta da ciascun endpoint
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Errori nella struttura della query
</div>

<AccordionGroup>
  <Accordion title="Selezioni mancanti">
    **Errore:** `at least one field or aggregation is required`

    **Causa:** La richiesta della query non contiene selezioni né aggregazioni.

    **Soluzione:** Aggiungi almeno una selezione alla richiesta della query:

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

  <Accordion title="Origine dati non valida">
    **Errore:** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

    **Causa:** Probabilmente c'è un errore di battitura nel campo `data_source`.

    **Soluzione:** Verifica che l'origine dati sia scritta correttamente. Opzioni valide:

    * `QUERY_DATA_SOURCE_USER_DATA`
    * `QUERY_DATA_SOURCE_CHAT_DATA`
    * `QUERY_DATA_SOURCE_COMMAND_DATA`
    * `QUERY_DATA_SOURCE_PCW_DATA`
  </Accordion>

  <Accordion title="Funzioni di aggregazione miste">
    **Errore:** `all selection fields should have an aggregation function, or none of them should`

    **Causa:** Alcune selezioni hanno una funzione di aggregazione, mentre altre no.

    **Soluzione:** Aggiungi una funzione di aggregazione a tutte le selezioni oppure rimuovila da tutte:

    **Non valido:**

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

    **Valido:**

    ```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">
  ### Errori dei campi e delle aggregazioni
</div>

<AccordionGroup>
  <Accordion title="Funzione di aggregazione non valida">
    **Errore:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **Causa:** La funzione di aggregazione non è supportata per il tipo di campo specificato.

    **Soluzione:** Verificare la sezione [Campi disponibili](/it/desktop/accounts/api-reference/custom-analytics#available-fields) per vedere quali funzioni di aggregazione sono valide per ciascun campo. I campi di tipo stringa in genere supportano solo `COUNT` e `UNSPECIFIED`.
  </Accordion>

  <Accordion title="Aggregazione su campi distinti">
    **Errore:** `tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]`

    **Causa:** I campi con il pattern "distinct\_\*" non possono essere usati nella sezione aggregations.

    **Soluzione:** Usare i campi alternativi suggeriti per l'aggregazione:

    **Non valido:**

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

    **Valido:**

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

  <Accordion title="Alias di campo duplicati">
    **Errore:** `duplicate field alias for selection/aggregation: num_acceptances`

    **Causa:** Più selezioni o aggregazioni hanno lo stesso nome.

    **Soluzione:** Assicurarsi che tutti gli alias dei campi siano univoci. Ricordare che, se non viene specificato alcun nome, il valore predefinito è `{aggregation_function}_{field_name}`.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Errori di filtro dei dati
</div>

<AccordionGroup>
  <Accordion title="Nome gruppo non valido">
    **Errore:** `invalid group name: GroupName`

    **Causa:** Il nome del gruppo specificato non esiste nella tua organizzazione.

    **Soluzione:**

    * Controlla attentamente l'ortografia del nome del gruppo
    * Verifica che il gruppo esista nelle impostazioni del team
    * Usa il nome del gruppo esattamente come appare nella dashboard del team
  </Accordion>

  <Accordion title="Formato timestamp non valido">
    **Errore:** `invalid timestamp format`

    **Causa:** Il timestamp non è nel corretto formato RFC 3339.

    **Soluzione:** Usa il formato timestamp corretto:

    ```
    2023-01-01T00:00:00Z
    ```

    **Esempi validi:**

    * `2024-01-01T00:00:00Z`
    * `2024-12-31T23:59:59Z`
    * `2024-06-15T12:30:45Z`
  </Accordion>

  <Accordion title="Filtri in conflitto">
    **Errore:** `Cannot use both group_name and emails parameters`

    **Causa:** In una richiesta a Cascade Analytics sono stati specificati sia il parametro `group_name` sia il parametro `emails`.

    **Soluzione:** Usa `group_name` OPPURE `emails`, ma non entrambi:

    **Non valido:**

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

    **Valido:**

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

    **Oppure:**

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

<div id="rate-limiting">
  ## Limitazione della frequenza delle richieste
</div>

<AccordionGroup>
  <Accordion title="Limite di frequenza superato">
    **Errore:** `429 Too Many Requests`

    **Causa:** Hai superato il limite di frequenza dell'API.

    **Soluzione:**

    * Attendi prima di inviare altre richieste
    * Implementa un backoff esponenziale nel client
    * Se possibile, valuta di raggruppare più query in un'unica richiesta
    * Contatta il supporto se hai bisogno di limiti di frequenza più elevati
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Consigli per il debug
</div>

<div id="1-start-simple">
  ### 1. Inizia in modo semplice
</div>

Parti con query di base e aggiungi gradualmente complessità:

```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. Verifica i nomi dei campi
</div>

Ricontrolla i nomi dei campi nella documentazione [Campi disponibili](/it/desktop/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Verifica la compatibilità delle aggregazioni
</div>

Assicurati che le funzioni di aggregazione siano compatibili con i tipi di campo che stai selezionando.

<div id="4-test-filters-separately">
  ### 4. Prova i filtri separatamente
</div>

Se la query non restituisce i risultati attesi, prova a rimuovere i filtri uno alla volta per individuare il problema.

<div id="5-use-proper-json-formatting">
  ### 5. Usa una formattazione JSON corretta
</div>

Assicurati che il JSON sia formattato correttamente e che tutte le stringhe siano racchiuse correttamente tra virgolette.

<div id="getting-help">
  ## Assistenza
</div>

Se continui a riscontrare problemi:

1. **Verifica attentamente il messaggio di errore** - La maggior parte degli errori include istruzioni specifiche su come risolvere il problema
2. **Esamina gli esempi** - Confronta la struttura della query con gli esempi funzionanti nella documentazione
3. **Contatta il supporto** - Rivolgiti a [Devin Desktop Support](https://windsurf.com/support) indicando il messaggio di errore specifico e la query

<div id="api-version-notes">
  ## Note sulle versioni dell'API
</div>

La gestione degli errori e la convalida sono state migliorate a partire dalla versione 1.10.0 dell'API. Se utilizzi una versione precedente, valuta l'aggiornamento per ottenere messaggi di errore più dettagliati.