​
Aperçu

L’Analytics API renvoie des messages d’erreur détaillés pour aider à diagnostiquer les requêtes invalides. Cette page présente les erreurs les plus courantes et explique comment les résoudre.

​
Format de réponse en cas d’erreur

Lorsqu’une erreur se produit, l’API renvoie une réponse d’erreur accompagnée d’un message explicite : 
{
  "error": "Message d'erreur décrivant ce qui a mal fonctionné"
}

​
Erreurs fréquentes

​
Erreurs d’authentification

Erreur : Invalid service keyCause : La clé de service fournie n’est pas valide ou a été révoquée.Solution :
  • Vérifiez que votre clé de service est correcte
  • Vérifiez que la clé de service n’a pas été révoquée
  • Générez une nouvelle clé de service si nécessaire
Erreur : Insufficient permissionsCause : La clé de service ne dispose pas des autorisations requises « Teams Read-only ».Solution :
  • Mettez à jour les autorisations de la clé de service dans les paramètres de l’équipe
  • Assurez-vous que la clé de service dispose de l’accès « Teams Read-only »

​
Erreurs de structure de requête

Erreur : at least one field or aggregation is requiredCause : La requête ne contient aucune sélection ni agrégation.Solution : Ajoutez au moins une sélection à votre requête :
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Erreur : invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDCause : Il y a probablement une faute de frappe dans le champ data_source.Solution : Vérifiez l’orthographe de votre source de données. Options valides :
  • QUERY_DATA_SOURCE_USER_DATA
  • QUERY_DATA_SOURCE_CHAT_DATA
  • QUERY_DATA_SOURCE_COMMAND_DATA
  • QUERY_DATA_SOURCE_PCW_DATA
Erreur : all selection fields should have an aggregation function, or none of them shouldCause : Certaines sélections ont des fonctions d’agrégation tandis que d’autres n’en ont pas.Solution : Ajoutez des fonctions d’agrégation à toutes les sélections ou supprimez-les partout :Non valide :
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]
Valide :
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​
Erreurs de champ et d’agrégation

Erreur : invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMCause : La fonction d’agrégation n’est pas prise en charge pour le type de champ spécifié.Solution : Consultez la section Champs disponibles pour voir quelles fonctions d’agrégation sont valides pour chaque champ. Les champs de type chaîne prennent généralement uniquement en charge COUNT et UNSPECIFIED.
Erreur : tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]Cause : Les champs suivant le motif « distinct_* » ne peuvent pas être utilisés dans la section aggregations.Solution : Utilisez les champs alternatifs suggérés pour l’agrégation :Non valide :
"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]
Valide :
"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]
Erreur : duplicate field alias for selection/aggregation: num_acceptancesCause : Plusieurs selections ou aggregations portent le même nom.Solution : Assurez-vous que tous les alias de champ sont uniques. N’oubliez pas que si aucun nom n’est spécifié, la valeur par défaut est {aggregation_function}_{field_name}.

​
Erreurs de filtrage des données

Erreur : invalid group name: GroupNameCause : Le nom de groupe indiqué n’existe pas dans votre organisation.Solution :
  • Vérifiez l’orthographe du nom de groupe
  • Assurez-vous que le groupe existe dans les paramètres de votre équipe
  • Utilisez exactement le nom de groupe tel qu’il apparaît dans le tableau de bord de votre équipe
Erreur : invalid timestamp formatCause : L’horodatage n’est pas au format RFC 3339.Solution : Utilisez le format d’horodatage correct :
2023-01-01T00:00:00Z
Exemples valides :
  • 2024-01-01T00:00:00Z
  • 2024-12-31T23:59:59Z
  • 2024-06-15T12:30:45Z
Erreur : Cannot use both group_name and emails parametersCause : Les paramètres group_name et emails ont été fournis simultanément dans une requête Cascade Analytics.Solution : Utilisez soit group_name, soit emails, mais pas les deux :Exemple invalide :
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
Exemple valide :
{
  "group_name": "engineering"
}
Ou :
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Limitation du débit

Erreur : 429 Too Many RequestsCause : Vous avez dépassé la limite de taux de l’API.Solution :
  • Patientez avant d’effectuer de nouvelles requêtes
  • Mettez en place un backoff exponentiel côté client
  • Envisagez de regrouper plusieurs requêtes en une seule lorsque c’est possible
  • Contactez l’assistance si vous avez besoin de limites plus élevées

​
Conseils pour le débogage

​
1. Commencez simplement

Commencez par des requêtes simples, puis ajoutez progressivement de la complexité : 
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. Valider les noms de champs

Vérifiez attentivement les noms de champs en les comparant à la documentation Champs disponibles.

​
3. Vérifiez la compatibilité des agrégations

Assurez-vous que vos fonctions d’agrégation sont compatibles avec les types de champs que vous sélectionnez.

​
4. Tester les filtres séparément

Si votre requête ne renvoie pas les résultats attendus, essayez de retirer les filtres un à un pour isoler le problème.

​
5. Utiliser un formatage JSON approprié

Assurez-vous que votre JSON est correctement formaté et que toutes les chaînes sont correctement entre guillemets.

​
Obtenir de l’aide

Si vous continuez à rencontrer des problèmes :
  1. Vérifiez attentivement le message d’erreur — La plupart des erreurs fournissent des indications précises pour résoudre le problème
  2. Consultez les exemples — Comparez la structure de votre requête aux exemples opérationnels de la documentation
  3. Contactez l’assistance — Adressez-vous à Windsurf Support avec votre message d’erreur et votre requête spécifiques

​
Notes de version de l’API

La gestion des erreurs et la validation ont été améliorées à partir de la version 1.10.0 de l’API. Si vous utilisez une version antérieure, envisagez de mettre à jour afin de bénéficier de messages d’erreur plus détaillés.