Vai al contenuto principale

​
Panoramica

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.

​
Formato della risposta d’errore

Quando si verifica un errore, l’API restituisce una risposta d’errore con un messaggio descrittivo: 
{
  "error": "Error message describing what went wrong"
}

​
Errori comuni

​
Errori di autenticazione

Errore: Invalid service keyCausa: 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
Errore: Insufficient permissionsCausa: 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 per l’autorizzazione specifica richiesta da ciascun endpoint

​
Errori nella struttura della query

Errore: at least one field or aggregation is requiredCausa: La richiesta della query non contiene selezioni né aggregazioni.Soluzione: Aggiungi almeno una selezione alla richiesta della query:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Errore: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCausa: 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
Errore: all selection fields should have an aggregation function, or none of them shouldCausa: 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:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]
Valido:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​
Errori dei campi e delle aggregazioni

Errore: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCausa: La funzione di aggregazione non è supportata per il tipo di campo specificato.Soluzione: Verificare la sezione Campi disponibili per vedere quali funzioni di aggregazione sono valide per ciascun campo. I campi di tipo stringa in genere supportano solo COUNT e UNSPECIFIED.
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:
"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]
Valido:
"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]
Errore: duplicate field alias for selection/aggregation: num_acceptancesCausa: 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}.

​
Errori di filtro dei dati

Errore: invalid group name: GroupNameCausa: 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
Errore: invalid timestamp formatCausa: 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
Errore: Cannot use both group_name and emails parametersCausa: 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:
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
Valido:
{
  "group_name": "engineering"
}
Oppure:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Limitazione della frequenza delle richieste

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

​
Consigli per il debug

​
1. Inizia in modo semplice

Parti con query di base e aggiungi gradualmente complessità: 
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. Verifica i nomi dei campi

Ricontrolla i nomi dei campi nella documentazione Campi disponibili.

​
3. Verifica la compatibilità delle aggregazioni

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

​
4. Prova i filtri separatamente

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

​
5. Usa una formattazione JSON corretta

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

​
Assistenza

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 indicando il messaggio di errore specifico e la query

​
Note sulle versioni dell’API

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.