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

# Fehlerbehandlung

> Häufige Fehlermeldungen und Tipps zur Fehlerbehebung für die Analytics-API, einschließlich Fehlern bei der Authentifizierung, der Abfragestruktur und der Ratenbegrenzung.

<div id="overview">
  ## Überblick
</div>

Die Analytics-API gibt detaillierte Fehlermeldungen zurück, um die Fehlersuche bei ungültigen Abfragen zu erleichtern. Auf dieser Seite werden häufige Fehlerszenarien und deren Behebung erläutert.

<div id="error-response-format">
  ## Format von Fehlerantworten
</div>

Wenn ein Fehler auftritt, gibt die API eine Fehlerantwort mit einer aussagekräftigen Meldung zurück:

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

<div id="common-errors">
  ## Häufige Fehler
</div>

<div id="authentication-errors">
  ### Authentifizierungsfehler
</div>

<AccordionGroup>
  <Accordion title="Ungültiger Service-Schlüssel">
    **Fehler:** `Invalid service key`

    **Ursache:** Der angegebene Service-Schlüssel ist ungültig oder wurde widerrufen.

    **Lösung:**

    * Vergewissern Sie sich, dass Ihr Service-Schlüssel korrekt ist
    * Stellen Sie sicher, dass der Service-Schlüssel nicht widerrufen wurde
    * Erstellen Sie bei Bedarf einen neuen Service-Schlüssel
  </Accordion>

  <Accordion title="Unzureichende Berechtigungen">
    **Fehler:** `Insufficient permissions`

    **Ursache:** Der Service-Schlüssel verfügt nicht über die erforderlichen Berechtigungen für den Endpunkt, den Sie aufrufen.

    **Lösung:**

    * Aktualisieren Sie die Berechtigungen des Service-Schlüssels in Team Settings
    * Welche Berechtigung für den jeweiligen Endpunkt erforderlich ist, finden Sie in der [API-Einführung](/de/desktop/accounts/api-reference/api-introduction#required-permissions)
  </Accordion>
</AccordionGroup>

<div id="query-structure-errors">
  ### Fehler in der Abfragestruktur
</div>

<AccordionGroup>
  <Accordion title="Fehlende Auswahlfelder">
    **Fehler:** `at least one field or aggregation is required`

    **Ursache:** Die Abfrageanfrage enthält keine Auswahlfelder oder Aggregationen.

    **Lösung:** Füge deiner Abfrageanfrage mindestens ein Auswahlfeld hinzu:

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

  <Accordion title="Ungültige Datenquelle">
    **Fehler:** `invalid query table: QUERY_DATA_SOURCE_UNSPECIFIED`

    **Ursache:** Wahrscheinlich liegt ein Tippfehler im Feld `data_source` vor.

    **Lösung:** Überprüfe die Schreibweise deiner Datenquelle noch einmal. Gültige Optionen:

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

  <Accordion title="Gemischte Aggregationsfunktionen">
    **Fehler:** `all selection fields should have an aggregation function, or none of them should`

    **Ursache:** Einige Auswahlfelder haben Aggregationsfunktionen, andere nicht.

    **Lösung:** Füge entweder allen Auswahlfeldern Aggregationsfunktionen hinzu oder entferne sie bei allen:

    **Ungültig:**

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

    **Gültig:**

    ```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">
  ### Fehler bei Feldern und Aggregationen
</div>

<AccordionGroup>
  <Accordion title="Ungültige Aggregationsfunktion">
    **Fehler:** `invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUM`

    **Ursache:** Die Aggregationsfunktion wird für den angegebenen Feldtyp nicht unterstützt.

    **Lösung:** Im Abschnitt [Verfügbare Felder](/de/desktop/accounts/api-reference/custom-analytics#available-fields) sehen Sie, welche Aggregationsfunktionen für die einzelnen Felder gültig sind. String-Felder unterstützen in der Regel nur `COUNT` und `UNSPECIFIED`.
  </Accordion>

  <Accordion title="Aggregation eines Distinct-Felds">
    **Fehler:** `tried to aggregate on a distinct field: distinct_developer_days. Consider aggregating on the non-distinct fields instead: [api_key date]`

    **Ursache:** Felder mit dem Muster „distinct\_\*“ können nicht im Abschnitt `aggregations` verwendet werden.

    **Lösung:** Verwenden Sie stattdessen die vorgeschlagenen alternativen Felder für die Aggregation:

    **Ungültig:**

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

    **Gültig:**

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

  <Accordion title="Doppelte Feldaliase">
    **Fehler:** `duplicate field alias for selection/aggregation: num_acceptances`

    **Ursache:** Mehrere Auswahlen oder Aggregationen haben denselben Namen.

    **Lösung:** Stellen Sie sicher, dass alle Feldaliase eindeutig sind. Beachten Sie, dass standardmäßig `{aggregation_function}_{field_name}` verwendet wird, wenn kein Name angegeben ist.
  </Accordion>
</AccordionGroup>

<div id="data-filtering-errors">
  ### Fehler bei der Datenfilterung
</div>

<AccordionGroup>
  <Accordion title="Ungültiger Gruppenname">
    **Fehler:** `invalid group name: GroupName`

    **Ursache:** Der angegebene Gruppenname existiert in Ihrer Organisation nicht.

    **Lösung:**

    * Überprüfen Sie die Schreibweise des Gruppennamens
    * Vergewissern Sie sich, dass die Gruppe in Ihren Team Settings vorhanden ist
    * Verwenden Sie den Gruppennamen exakt so, wie er in Ihrem Team-Dashboard angezeigt wird
  </Accordion>

  <Accordion title="Ungültiges Zeitstempelformat">
    **Fehler:** `invalid timestamp format`

    **Ursache:** Der Zeitstempel entspricht nicht dem korrekten RFC-3339-Format.

    **Lösung:** Verwenden Sie das korrekte Zeitstempelformat:

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

    **Gültige Beispiele:**

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

  <Accordion title="Konfliktierende Filter">
    **Fehler:** `Cannot use both group_name and emails parameters`

    **Ursache:** In einer Cascade-Analytics-Anfrage wurden sowohl die Parameter `group_name` als auch `emails` angegeben.

    **Lösung:** Verwenden Sie entweder `group_name` ODER `emails`, aber nicht beide zusammen:

    **Ungültig:**

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

    **Gültig:**

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

    **Oder:**

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

<div id="rate-limiting">
  ## Ratenbegrenzung
</div>

<AccordionGroup>
  <Accordion title="Rate-Limit überschritten">
    **Fehler:** `429 Too Many Requests`

    **Ursache:** Sie haben das API-Rate-Limit überschritten.

    **Lösung:**

    * Warten Sie einen Moment, bevor Sie weitere Anfragen senden
    * Implementieren Sie exponentielles Backoff in Ihrem Client
    * Fassen Sie nach Möglichkeit mehrere Abfragen in einer einzelnen Anfrage zusammen
    * Wenden Sie sich an den Support, wenn Sie ein höheres Rate-Limit benötigen
  </Accordion>
</AccordionGroup>

<div id="debugging-tips">
  ## Tipps zum Debuggen
</div>

<div id="1-start-simple">
  ### 1. Einfach anfangen
</div>

Beginnen Sie mit einfachen Abfragen und erhöhen Sie die Komplexität schrittweise:

```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. Feldnamen überprüfen
</div>

Überprüfen Sie die Feldnamen noch einmal anhand der Dokumentation zu [Verfügbare Felder](/de/desktop/accounts/api-reference/custom-analytics#available-fields).

<div id="3-check-aggregation-compatibility">
  ### 3. Kompatibilität von Aggregationen prüfen
</div>

Stellen Sie sicher, dass Ihre Aggregationsfunktionen mit den Feldtypen kompatibel sind, die Sie auswählen.

<div id="4-test-filters-separately">
  ### 4. Filter einzeln testen
</div>

Wenn Ihre Abfrage nicht die erwarteten Ergebnisse liefert, versuchen Sie, die Filter nacheinander zu entfernen, um das Problem einzugrenzen.

<div id="5-use-proper-json-formatting">
  ### 5. JSON korrekt formatieren
</div>

Stellen Sie sicher, dass Ihr JSON korrekt formatiert ist und alle Strings richtig in Anführungszeichen stehen.

<div id="getting-help">
  ## Hilfe erhalten
</div>

Wenn weiterhin Probleme auftreten:

1. **Prüfen Sie die Fehlermeldung sorgfältig** - Die meisten Fehler enthalten konkrete Hinweise zur Behebung des Problems
2. **Überprüfen Sie die Beispiele** - Vergleichen Sie die Struktur Ihrer Abfrage mit den funktionierenden Beispielen in der Dokumentation
3. **Kontaktieren Sie den Support** - Wenden Sie sich mit Ihrer konkreten Fehlermeldung und Ihrer Abfrage an den [Devin Desktop Support](https://windsurf.com/support)

<div id="api-version-notes">
  ## Hinweise zur API-Version
</div>

Die Fehlerbehandlung und Validierung wurden ab API-Version 1.10.0 verbessert. Wenn Sie eine ältere Version verwenden, sollten Sie ein Update erwägen, um detailliertere Fehlermeldungen zu erhalten.