Gestione degli errori

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

Chiave di servizio non valida

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

Autorizzazioni insufficienti

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

Selezioni mancanti

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"
  }
]

Origine dati non valida

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

Funzioni di aggregazione miste

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

Funzione di aggregazione non valida

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.

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:

"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]

Valido:

"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]

Alias di campo duplicati

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

Nome gruppo non valido

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

Formato timestamp non valido

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

Filtri in conflitto

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

Limite di frequenza superato

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:

Verifica attentamente il messaggio di errore - La maggior parte degli errori include istruzioni specifiche su come risolvere il problema
Esamina gli esempi - Confronta la struttura della query con gli esempi funzionanti nella documentazione
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.

Devin Desktop

Centro di comando degli agenti

Release

Plugin di Windsurf

Account

Sicurezza

Gestione degli errori

Panoramica

Formato della risposta d’errore

Errori comuni

Errori di autenticazione

Errori nella struttura della query

Errori dei campi e delle aggregazioni

Errori di filtro dei dati

Limitazione della frequenza delle richieste

Consigli per il debug

1. Inizia in modo semplice

2. Verifica i nomi dei campi

3. Verifica la compatibilità delle aggregazioni

4. Prova i filtri separatamente

5. Usa una formattazione JSON corretta

Assistenza

Note sulle versioni dell’API

​Panoramica

​Formato della risposta d’errore

​Errori comuni

​Errori di autenticazione

​Errori nella struttura della query

​Errori dei campi e delle aggregazioni

​Errori di filtro dei dati

​Limitazione della frequenza delle richieste

​Consigli per il debug

​1. Inizia in modo semplice

​2. Verifica i nomi dei campi

​3. Verifica la compatibilità delle aggregazioni

​4. Prova i filtri separatamente

​5. Usa una formattazione JSON corretta

​Assistenza

​Note sulle versioni dell’API

Panoramica

Formato della risposta d’errore

Errori comuni

Errori di autenticazione

Errori nella struttura della query

Errori dei campi e delle aggregazioni

Errori di filtro dei dati

Limitazione della frequenza delle richieste

Consigli per il debug

1. Inizia in modo semplice

2. Verifica i nomi dei campi

3. Verifica la compatibilità delle aggregazioni

4. Prova i filtri separatamente

5. Usa una formattazione JSON corretta

Assistenza

Note sulle versioni dell’API