Fehlerbehandlung

Ü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

Invalid service key

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

Insufficient permissions

Fehler: Insufficient permissionsUrsache: Der Service Key verfügt nicht über die erforderlichen Berechtigungen für den Endpunkt, den Sie aufrufen.Lösung:

Aktualisieren Sie die Service-Key-Berechtigungen in den Team-Einstellungen
Weitere Informationen zu den für die einzelnen Endpunkte erforderlichen Berechtigungen finden Sie in der API-Einführung

Fehler in der Abfragestruktur

Fehlende selections

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"
  }
]

Ungültige data_source

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

Gemischte aggregation functions

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

Ungültige Aggregationsfunktion

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.

Aggregation auf Distinct-Feld

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"
  }
]

Doppelte Feldaliase

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

Ungültiger Gruppenname

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

Ungültiges Zeitstempelformat

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

Widersprüchliche Filter

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

Rate Limit überschritten

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:

Prüfen Sie die Fehlermeldung sorgfältig – die meisten enthalten konkrete Hinweise zur Behebung
Sehen Sie sich die Beispiele an – vergleichen Sie die Struktur Ihrer Anfrage mit den funktionierenden Beispielen in der Dokumentation
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.

Editor

Cascade

Konten

Kontextverständnis

Fehlerbehebung

Sicherheit

Übersicht

Fehlerantwortformat

Häufige Fehler

Authentifizierungsfehler

Fehler in der Abfragestruktur

Feld- und Aggregationsfehler

Fehler bei der Datenfilterung

Rate Limiting

Tipps zum Debuggen

1. Starten Sie einfach

2. Feldnamen überprüfen

3. Kompatibilität der Aggregation prüfen

4. Filter separat testen

5. Verwenden Sie eine korrekte JSON-Formatierung

Hilfe erhalten

Hinweise zur API-Version