​
Überblick

Die Analytics-API gibt detaillierte Fehlermeldungen zurück, um beim Debuggen ungültiger Abfragen zu helfen. Diese Seite beschreibt häufige Fehlerszenarien und wie man sie behebt.

​
Fehlerantwortformat

Wenn ein Fehler auftritt, gibt die API eine Fehlerantwort mit einer aussagekräftigen Fehlermeldung zurück: 
{
  "error": "Fehlermeldung, die beschreibt, was schiefgelaufen ist"
}

​
Häufige Fehler

​
Authentifizierungsfehler

Fehler: Invalid service keyUrsache: Der angegebene Service Key ist ungültig oder wurde widerrufen.Lösung:
  • Überprüfen Sie, ob Ihr Service Key korrekt ist
  • Stellen Sie sicher, dass der Service Key nicht widerrufen wurde
  • Generieren Sie bei Bedarf einen neuen Service Key
Fehler: Insufficient permissionsUrsache: Der Service Key verfügt nicht über die erforderlichen „Teams Nur-Lesen“-Berechtigungen.Lösung:
  • Aktualisieren Sie die Service-Key-Berechtigungen in den Team-Einstellungen
  • Stellen Sie sicher, dass der Service Key über „Teams Nur-Lesen“-Zugriff verfügt

​
Fehler in der Abfragestruktur

Fehler: at least one field or aggregation is requiredUrsache: Die Anfrage enthält keine selections oder aggregations.Lösung: Füge deiner Anfrage mindestens eine selection hinzu:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]
Fehler: invalid query table: QUERY_DATA_SOURCE_UNSPECIFIEDUrsache: Wahrscheinlich gibt es einen Tippfehler im Feld data_source.Lösung: Überprüfe die Schreibweise deiner Datenquelle. Gültige Optionen:
  • QUERY_DATA_SOURCE_USER_DATA
  • QUERY_DATA_SOURCE_CHAT_DATA
  • QUERY_DATA_SOURCE_COMMAND_DATA
  • QUERY_DATA_SOURCE_PCW_DATA
Fehler: all selection fields should have an aggregation function, or none of them shouldUrsache: Einige selections haben Aggregationsfunktionen, andere nicht.Lösung: Füge entweder allen selections Aggregationsfunktionen hinzu oder entferne sie bei allen:Ungültig:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_UNSPECIFIED"
  }
]
Gültig:
"selections": [
  {
    "field": "num_acceptances",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  },
  {
    "field": "num_lines_accepted",
    "aggregation_function": "QUERY_AGGREGATION_SUM"
  }
]

​
Feld- und Aggregationsfehler

Fehler: invalid aggregation function for string type field ide: QUERY_AGGREGATION_SUMUrsache: Die Aggregationsfunktion wird für den angegebenen Feldtyp nicht unterstützt.Lösung: Sehen Sie im Abschnitt Available Fields nach, welche Aggregationsfunktionen für die einzelnen Felder zulässig sind. String-Felder unterstützen in der Regel nur COUNT und UNSPECIFIED.
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 die vorgeschlagenen alternativen Felder für die Aggregation:Ungültig:
"aggregations": [
  {
    "field": "distinct_developer_days",
    "name": "distinct_developer_days"
  }
]
Gültig:
"aggregations": [
  {
    "field": "api_key",
    "name": "api_key"
  },
  {
    "field": "date",
    "name": "date"
  }
]
Fehler: duplicate field alias for selection/aggregation: num_acceptancesUrsache: Mehrere selections oder aggregations haben denselben Namen.Lösung: Stellen Sie sicher, dass alle Feldaliase eindeutig sind. Beachten Sie, dass, wenn kein Name angegeben ist, standardmäßig {aggregation_function}_{field_name} verwendet wird.

​
Fehler bei der Datenfilterung

Fehler: invalid group name: GroupNameUrsache: Der angegebene Gruppenname ist in Ihrer Organisation nicht vorhanden.Lösung:
  • Überprüfen Sie die Schreibweise des Gruppennamens
  • Prüfen Sie in den Team-Einstellungen, ob die Gruppe existiert
  • Nutzen Sie den exakten Gruppennamen, wie er im Team-Dashboard angezeigt wird
Fehler: invalid timestamp formatUrsache: 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
Fehler: Cannot use both group_name and emails parametersUrsache: Sowohl die Parameter group_name als auch emails wurden in einer Cascade Analytics-Anfrage übergeben.Lösung: Verwenden Sie entweder group_name ODER emails, aber nicht beide:Ungültig:
{
  "group_name": "engineering",
  "emails": ["user@example.com"]
}
Gültig:
{
  "group_name": "engineering"
}
Oder:
{
  "emails": ["user@example.com", "user2@example.com"]
}

​
Rate Limiting

Fehler: 429 Too Many RequestsUrsache: Sie haben das API-Rate Limit überschritten.Lösung:
  • Warten Sie, bevor Sie weitere Requests senden
  • Implementieren Sie exponentielles Backoff in Ihrem Client
  • Bündeln Sie nach Möglichkeit mehrere Queries zu einem einzelnen Request
  • Kontaktieren Sie den Support, wenn Sie höhere Rate Limits benötigen

​
Tipps zum Debuggen

​
1. Einfach beginnen

Starten Sie mit einfachen Anfragen und steigern Sie nach und nach die Komplexität: 
{
  "service_key": "your_key",
  "query_requests": [
    {
      "data_source": "QUERY_DATA_SOURCE_USER_DATA",
      "selections": [
        {
          "field": "num_acceptances",
          "aggregation_function": "QUERY_AGGREGATION_COUNT"
        }
      ]
    }
  ]
}

​
2. Feldnamen prüfen

Vergleichen Sie die Feldnamen mit der Dokumentation zu Available Fields.

​
3. Kompatibilität der Aggregation prüfen

Stellen Sie sicher, dass Ihre Aggregationsfunktionen mit den Typen der ausgewählten Felder kompatibel sind.

​
4. Filter separat testen

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

​
5. Verwenden Sie korrektes JSON-Formatting

Stellen Sie sicher, dass Ihr JSON korrekt formatiert ist und alle Zeichenketten korrekt in Anführungszeichen gesetzt sind.

​
Hilfe erhalten

Wenn das Problem weiterhin auftritt:
  1. Prüfen Sie die Fehlermeldung genau – die meisten Fehler enthalten konkrete Hinweise zur Behebung
  2. Überprüfen Sie die Beispiele – vergleichen Sie die Struktur Ihrer Anfrage mit den funktionierenden Beispielen in der Dokumentation
  3. Kontaktieren Sie den Support – wenden Sie sich mit Ihrer konkreten Fehlermeldung und Anfrage an den Windsurf Support

​
Hinweise zur API-Version

Die Fehlerbehandlung und Validierung wurden ab API-Version 1.10.0 verbessert. Wenn Sie eine ältere Version verwenden, sollten Sie ein Update in Erwägung ziehen, um ausführlichere Fehlermeldungen zu erhalten.