Docs
Dashboard

Fehler

Alle Fehlerantworten der Scrumball-API nutzen dieselbe JSON-Hülle: success ist false, code enthält den HTTP-Status und message eine kurze Erklärung. Die folgenden Abschnitte erklären, was jeder Status bedeutet, wodurch er typischerweise entsteht und wie er behoben wird.

Aufbau der Fehlerantwort

json
{
  "success": false,
  "code": 400,
  "message": "Bad Request"
}

400Bad Request

Bedeutung

Der Server konnte die Anfrage nicht verarbeiten oder annehmen; sie wurde vor der Fachlogik abgewiesen.

Häufige Ursachen

  • Der Request-Body ist kein gültiges JSON (POST-Endpunkte wie search oder das Anlegen von Monitoring-Aufgaben).
  • Content-Type ist nicht auf application/json gesetzt.
  • Ein Query-Parameter hat das falsche Format, etwa ein Datum im falschen Format.
  • Ein Tippfehler im Pfad führte zur falschen Route.

Lösung

  1. Prüfen Sie, ob Pfad und HTTP-Methode mit der Referenzseite des Endpunkts übereinstimmen.
  2. Stellen Sie bei POST-Endpunkten sicher, dass die Anfrage Content-Type: application/json enthält.
  3. Prüfen Sie den Body mit einem JSON-Validator auf Gültigkeit.
  4. Gehen Sie die Tabelle der Pflichtparameter auf der Endpunktseite durch und prüfen Sie jeden Namen und jedes Format.

401Unauthorized

Bedeutung

Der Anfrage fehlt ein gültiger API-Schlüssel, daher kann der Server den Aufrufer nicht identifizieren.

Häufige Ursachen

  • Der Authorization-Header wurde nicht gesendet.
  • Vor dem Schlüssel wurde ein Bearer-Präfix ergänzt (diese API erwartet den reinen Schlüssel ohne Präfix).
  • Der Schlüssel wurde gelöscht oder gewechselt, der Client nutzt weiterhin den alten Wert.
  • Beim Kopieren ist ein Leerzeichen oder Zeilenumbruch in den Schlüssel geraten.

Lösung

  1. Prüfen Sie, dass der Header exakt Authorization: YOUR_API_KEY ohne Präfix lautet.
  2. Prüfen Sie unter Dashboard > API Keys, ob der Schlüssel noch aktiv ist.
  3. Ist der Schlüssel ungültig, erstellen Sie einen neuen und aktualisieren Sie die serverseitige Umgebungsvariable.
  4. Prüfen Sie zuerst die Erreichbarkeit mit GET /api/ping und debuggen Sie danach den konkreten Endpunkt.

403Forbidden

Bedeutung

Der Aufrufer wurde erkannt, doch das Konto darf diesen Endpunkt nicht nutzen oder das Kontingent ist aufgebraucht.

Häufige Ursachen

  • Der aktuelle Tarif enthält diesen Endpunkt nicht (etwa Zielgruppenanalysen oder Echtzeit-Endpunkte).
  • Das Testkontingent ist aufgebraucht.
  • Das Abonnement ist abgelaufen.
  • Der Endpunkt ist für dieses Konto noch nicht freigeschaltet.

Lösung

  1. Prüfen Sie das verbleibende Kontingent unter Dashboard > Usage.
  2. Prüfen Sie unter Dashboard > Billing den Abo-Status und die im Tarif enthaltenen Endpunkte.
  3. Für höherwertige Endpunkte wechseln Sie den Tarif oder wenden Sie sich an den Support.
  4. Unterscheiden Sie 403 und 429: 403 ist ein Rechteproblem, 429 eine Ratenbegrenzung.

404Not Found

Bedeutung

Der angefragte Pfad existiert nicht, oder die angefragte Ressource ist nicht in der Datenbank vorhanden.

Häufige Ursachen

  • Der Endpunktpfad ist falsch geschrieben oder wurde eingestellt.
  • Die HTTP-Methode passt nicht (etwa eine GET-Anfrage an einen POST-Endpunkt).
  • Das Creator-Konto ist von der persistierten Datenbank nicht abgedeckt.
  • Das Video oder der Beitrag wurde gelöscht oder auf privat gestellt.

Lösung

  1. Prüfen Sie den vollständigen Pfad und die Methode anhand der Referenzseite des Endpunkts.
  2. Stellen Sie sicher, dass die Basis-URL https://openapi.scdata.cc ist und nicht die Domain der Dokumentationsseite.
  3. Wird ein Konto nicht gefunden, rufen Sie den passenden Echtzeit-Endpunkt auf, um eine Erfassung auszulösen.
  4. Unterscheiden Sie 404 von einer 200-Antwort mit data: null — Letztere bedeutet, der Pfad stimmt, es gibt aber keine Daten.

429Too Many Requests

Bedeutung

Die Anfragerate überschritt das Limit des aktuellen Tarifs, daher hat der Server gedrosselt.

Häufige Ursachen

  • Zu viele gleichzeitige Anfragen auf einmal.
  • Ein Batch-Job ohne Drosselung hat in kurzer Zeit viele Anfragen gesendet.
  • Mehrere Service-Instanzen teilen sich einen Schlüssel, ohne ihre Aufrufrate abzustimmen.
  • Die Wiederholungslogik hat kein Backoff, sodass sofortige Neuversuche nach einem Fehler die Last verstärken.

Lösung

  1. Reduzieren Sie die Parallelität und begrenzen Sie die Anzahl der Anfragen pro Zeiteinheit.
  2. Setzen Sie exponentielles Backoff ein: zuerst 1 Sekunde warten, dann jeweils verdoppeln, empfohlene Obergrenze 32 Sekunden.
  3. Verarbeiten Sie Batch-Lasten über eine Warteschlange, damit die Rate kontrolliert bleibt.
  4. Prüfen Sie die Verbrauchskurve unter Dashboard > Usage, um Spitzenzeiten zu erkennen.

500Server Error

Bedeutung

Beim Verarbeiten der Anfrage trat serverseitig eine unerwartete Ausnahme auf; die Anfrage selbst ist nicht die Ursache.

Häufige Ursachen

  • Eine vorgelagerte Plattform-Datenquelle ist vorübergehend nicht verfügbar.
  • Eine interne Server-Ausnahme.
  • Eine bestimmte Parameterkombination hat einen nicht abgedeckten Sonderfall ausgelöst.

Lösung

  1. Versuchen Sie es mit Backoff erneut; der Fehler verschwindet meist nach kurzer Wartezeit.
  2. Erfassen Sie den vollständigen Anfragekontext: Pfad, alle Parameter, Zeitpunkt und Antwort-Body.
  3. Tritt derselbe Fehler dauerhaft auf, wenden Sie sich mit diesem Kontext an den Support.
  4. Behandeln Sie 5xx und 4xx im Client unterschiedlich: 5xx kann wiederholt werden, bei 4xx muss die Anfrage korrigiert werden.