> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestion des erreurs

> Messages d’erreur courants et conseils de débogage pour l’Analytics API, y compris les erreurs liées à l’authentification, à la structure des requêtes et à la limitation de débit.

<div id="overview">
  ## Aperçu
</div>

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

<div id="error-response-format">
  ## Format de réponse d’erreur
</div>

Lorsqu’une erreur survient, l’API renvoie une réponse d’erreur accompagnée d’un message descriptif :

```json theme={null}
{
  "error": "Message d'erreur décrivant ce qui a mal fonctionné"
}
```

<div id="common-errors">
  ## Erreurs fréquentes
</div>

<div id="authentication-errors">
  ### Erreurs d’authentification
</div>

<AccordionGroup>
  <Accordion title="Clé de service invalide">
    **Erreur :** `Invalid service key`

    **Cause :** 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
    * Contrôlez que la clé de service n’a pas été révoquée
    * Générez une nouvelle clé de service si nécessaire
  </Accordion>

  <Accordion title="Autorisations insuffisantes">
    **Erreur :** `Insufficient permissions`

    **Cause :** La clé de service ne dispose pas des autorisations requises pour l’endpoint que vous appelez.

    **Solution :**

    * Mettez à jour les autorisations de la clé de service dans les paramètres de l’équipe
    * Consultez l’[introduction à l’API](/fr/plugins/accounts/api-reference/api-introduction#required-permissions) pour connaître l’autorisation spécifique requise par chaque endpoint
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Erreurs de structure de requête
</div>

<AccordionGroup>
  <Accordion title="Sélections manquantes">
    **Erreur :** `at least one field or aggregation is required`

    **Cause :** La requête ne contient aucune sélection ni agrégation.

    **Solution :** Ajoutez au moins une sélection à votre requête :

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

  <Accordion title="Source de données non valide">
    **Erreur :** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

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

  <Accordion title="Fonctions d’agrégation incohérentes">
    **Erreur :** `all selection fields should have an aggregation function, or none of them should`

    **Cause :** 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 de toutes :

    **Non valide :**

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

    **Valide :**

    ```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">
  ### Erreurs de champs et d’agrégation
</div>

<AccordionGroup>
  <Accordion title="Fonction d’agrégation non valide">
    **Erreur :** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **Cause :** La fonction d’agrégation n’est pas prise en charge pour le type de champ spécifié.

    **Solution :** Consultez la section [Available Fields](/fr/plugins/accounts/api-reference/custom-analytics#available-fields) pour voir quelles fonctions d’agrégation sont valides pour chaque champ. Les champs de type chaîne ne prennent généralement en charge que `COUNT` et `UNSPECIFIED`.
  </Accordion>

  <Accordion title="Agrégation sur champ distinct">
    **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 modèle « 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 :**

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

    **Valide :**

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

  <Accordion title="Alias de champ en double">
    **Erreur :** `duplicate field alias for selection/aggregation: num_acceptances`

    **Cause :** Plusieurs selections ou aggregations portent le même nom.

    **Solution :** Assurez-vous que tous les alias de champ sont uniques. Rappelez-vous que si aucun nom n’est spécifié, la valeur par défaut est `{aggregation_function}_{field_name}`.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Erreurs de filtrage des données
</div>

<AccordionGroup>
  <Accordion title="Nom de groupe non valide">
    **Erreur :** `invalid group name: GroupName`

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

  <Accordion title="Format d’horodatage non valide">
    **Erreur :** `invalid timestamp format`

    **Cause :** L’horodatage n’est pas au format RFC 3339 requis.

    **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`
  </Accordion>

  <Accordion title="Filtres en conflit">
    **Erreur :** `Cannot use both group_name and emails parameters`

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

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

    **Exemple valide :**

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

    **Ou :**

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

<div id="rate-limiting">
  ## Limitation du taux de requêtes
</div>

<AccordionGroup>
  <Accordion title="Limite de taux dépassée">
    **Erreur :** `429 Too Many Requests`

    **Cause :** 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 de taux plus élevées
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Conseils pour le débogage
</div>

<div id="1-start-simple">
  ### 1. Commencez simplement
</div>

Commencez par des requêtes simples et ajoutez progressivement en complexité :

```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. Valider les noms de champs
</div>

Vérifiez les noms de champs en les comparant à la documentation [Available Fields](/fr/plugins/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Vérifiez la compatibilité des agrégations
</div>

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

<div id="4-test-filters-separately">
  ### 4. Tester les filtres séparément
</div>

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

<div id="5-use-proper-json-formatting">
  ### 5. Utiliser un formatage JSON correct
</div>

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

<div id="getting-help">
  ## Obtenir de l’aide
</div>

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 fonctionnels de la documentation
3. **Contactez l’assistance** - Adressez-vous à [Windsurf Support](https://windsurf.com/support) avec votre message d’erreur et votre requête

<div id="api-version-notes">
  ## Notes de version de l’API
</div>

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 d’obtenir des messages d’erreur plus détaillés.