​
Übersicht

Die Analytics-API liefert detaillierte Fehlermeldungen, um ungültige Abfragen zu debuggen. 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 Meldung zurück: 
{
  "error": "Fehlermeldung, die beschreibt, was schiefgelaufen ist"
}

​
Häufige Fehler

​
Authentifizierungsfehler

Fehler: Invalid service keyUrsache: Der bereitgestellte 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 Abfrage enthält keine selections oder aggregations.Lösung: Fügen Sie Ihrer Abfrage 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üfen Sie die Schreibweise Ihrer data_source. 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 aggregation functions, andere nicht.Lösung: Fügen Sie entweder allen selections aggregation functions hinzu oder entfernen Sie sie überall: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. Zeichenfolgenfelder 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 im Abschnitt aggregations nicht 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: Wenn kein Name angegeben ist, lautet der Standard {aggregation_function}_{field_name}.

​
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, ob die Gruppe in Ihren Teameinstellungen existiert
  • Verwenden Sie den exakten Gruppennamen, wie er in Ihrem 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 übermittelt.Lösung: Verwenden Sie entweder group_name ODER emails, aber nicht beides: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 Anfragen senden
  • Implementieren Sie exponentielles Backoff in Ihrem Client
  • Fassen Sie nach Möglichkeit mehrere Abfragen zu einer Anfrage zusammen (Batching)
  • Kontaktieren Sie den Support, wenn Sie höhere Rate Limits benötigen

​
Tipps zum Debuggen

​
1. Starten Sie einfach

Beginnen Sie mit grundlegenden Anfragen und erhöhen Sie schrittweise 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 überprüfen

Prüfen Sie die Feldnamen anhand der Dokumentation zu Available Fields.

​
3. Kompatibilität der Aggregation prüfen

Stellen Sie sicher, dass Ihre Aggregationsfunktionen mit den ausgewählten Feldtypen 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 eine korrekte JSON-Formatierung

Stellen Sie sicher, dass Ihr JSON korrekt formatiert ist und alle Zeichenketten ordnungsgemäß in Anführungszeichen stehen.

​
Hilfe erhalten

Wenn weiterhin Probleme auftreten:
  1. Prüfen Sie die Fehlermeldung sorgfältig – die meisten enthalten konkrete Hinweise zur Behebung
  2. Sehen Sie sich die Beispiele an – vergleichen Sie die Struktur Ihrer Anfrage mit den funktionierenden Beispielen in der Dokumentation
  3. Kontaktieren Sie den Support – wenden Sie sich mit Ihrer spezifischen 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 Betracht ziehen, um ausführlichere Fehlermeldungen zu erhalten.