Fehler und Durchsatzbegrenzung

Fehler

Alle Fehlertypen außer ValidationError haben diese Struktur:

{
  "error": {
    "type": "NotFound",
    "message": "Resource not found.",
    "request_id": "req_6b1c9d2e4f3a5078b6c4d2e0"
  }
}

Beim Fehlertyp ValidationError kommen field_errors und non_field_errors hinzu:

{
  "error": {
    "type": "ValidationError",
    "message": "One or more fields are missing or have invalid values. See `field_errors` and `non_field_errors` for details.",
    "field_errors": {
      "due_date": ["This field is required."]
    },
    "non_field_errors": [],
    "request_id": "req_6b1c9d2e4f3a5078b6c4d2e0"
  }
}

Folgende Fehlertypen gibt es:

Typ	Statuscode	Beschreibung
`ValidationError`	400	Ein oder mehrere Felder fehlen oder haben ungültige Werte. Siehe `field_errors` und `non_field_errors` für mehr Details.
`ParseError`	400	Anfrage enthält fehlerhafte Daten.
`AuthenticationFailed`	401	Authentifizierung ist fehlgeschlagen: ungültiger Authentifizierung-Header oder ungültiger API-Schlüssel.
`NotAuthenticated`	401	Authentifizierung ist fehlgeschlagen: Der API-Schlüssel wurde nicht übermittelt.
`PermissionDenied`	403	Keine Berechtigung, diese Aktion durchzuführen.
`NotFound`	404	Ressource nicht gefunden.
`MethodNotAllowed`	405	HTTP-Methode ist nicht erlaubt.
`NotAcceptable`	406	Der Accept-Header der Anfrage konnte nicht erfüllt werden.
`UnsupportedMediaType`	415	Nicht unterstützter Medientyp in der Anfrage.
`Throttled`	429	Ein Limit der Durchsatzbegrenzung wurde erreicht.
`InternalServerError`	500	Ein interner Serverfehler ist aufgetreten.

Request-IDs

Jede API-Antwort enthält im HTTP-Header das Feld X-Request-ID mit einer eindeutigen ID wie req_6b1c9d2e4f3a5078b6c4d2e0; Fehlerantworten wiederholen sie als request_id im Fehlerbody. Geben Sie diese ID bei Support-Anfragen an: Damit können wir den betroffenen Request direkt in unseren Logs nachschlagen.

Durchsatzbegrenzung

Schulungstool setzt bei seiner API Durchsatzbegrenzung ein, um allen Benutzern eine konsistente API-Leistung zu gewährleisten. Standardmäßig kann jedes Schulungstool-Konto bis zu 1000 API-Anfragen pro Minute ausführen.

Jede Antwort zeigt den aktuellen Stand des Limits in drei HTTP-Headern an. So können Sie Ihre Anfragerate anpassen, bevor ein Limit erreicht wird:

Header	Bedeutung
`X-RateLimit-Limit`	Maximal erlaubte Anfragen im aktuellen Zeitfenster.
`X-RateLimit-Remaining`	Davon nach dieser Anfrage noch verfügbare Anfragen.
`X-RateLimit-Reset`	Zeitpunkt, zu dem wieder mindestens eine Anfrage frei wird, als Unix-Zeitstempel in Sekunden.

Ausnahme: Antworten mit Statuscode 401 tragen diese Header nicht, da ohne gültigen API-Schlüssel kein Konto zugeordnet werden kann.

Wenn ein Limit erreicht wurde, erhalten Sie eine HTTP-Antwort mit dem Statuscode 429:

{
  "error": {
    "type": "Throttled",
    "message": "Request was throttled. Expected available in 7 seconds."
  }
}

Die Antwort enthält im HTTP-Header das Feld Retry-After mit der Anzahl der zu wartenden Sekunden, nach denen bei einer erneuten Anfrage eine normale Antwort erwartet werden kann.

Retry-Empfehlungen

Beobachten Sie X-RateLimit-Remaining: Nähert sich der Wert 0, verteilen Sie weitere Anfragen bis zum Zeitpunkt aus X-RateLimit-Reset, statt in den 429 zu laufen.
Wiederholen Sie eine Anfrage nur bei Status 429 (warten Sie die in Retry-After angegebenen Sekunden ab) und bei 5xx-Fehlern (mit exponentiellem Backoff und einer begrenzten Zahl von Versuchen).
Wiederholen Sie andere 4xx-Fehler nicht: Die Anfrage selbst ist das Problem, und unverändert wiederholt schlägt sie erneut fehl. Korrigieren Sie stattdessen die Anfrage anhand von Fehlertyp und Meldung, siehe Tabelle oben.