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

Der Fehlertyp MissingScope ergänzt required_scope (das fehlende Zugriffsrecht, auch im Antwort-Header X-Required-Scope) und doc_url; siehe Zugriffsrechte.

Behandeln Sie die Liste der Fehlertypen in Ihrer Integration als offen: Mit der Zeit können neue Typen hinzukommen.

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.
`IdempotencyKeyInvalidError`	400	Der `Idempotency-Key`-Header ist ungültig, siehe Idempotente Requests.
`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.
`TokenExpired`	401	Das OAuth-Access-Token ist abgelaufen; erneuern Sie es mit dem Refresh-Token, siehe OAuth.
`AccountFrozen`	401	Das Schulungstool-Konto ist eingefroren; wenden Sie sich an den Support.
`MissingScope`	403	Dem API-Schlüssel fehlt das Zugriffsrecht, das dieser Endpunkt verlangt; `required_scope` nennt es. Siehe Zugriffsrechte.
`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.
`IdempotencyKeyInUseError`	409	Eine Anfrage mit demselben `Idempotency-Key` läuft noch, siehe Idempotente Requests.
`UnsupportedMediaType`	415	Nicht unterstützter Medientyp in der Anfrage.
`IdempotencyKeyReuseError`	422	Der `Idempotency-Key` wurde bereits für eine andere Anfrage verwendet, siehe Idempotente Requests.
`Throttled`	429	Ein Limit der Durchsatzbegrenzung wurde erreicht.
`AuthThrottled`	429	Zu viele fehlgeschlagene Authentifizierungsversuche für diesen API-Schlüssel; warten Sie die in `Retry-After` genannte Zeit ab.
`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. Es gelten diese Limits:

Limit	Gilt
1000 Anfragen pro Minute	je Schulungstool-Konto
600 Anfragen pro Minute	je API-Schlüssel bzw. OAuth-Verbindung, damit eine Integration nicht das ganze Kontingent des Kontos verbraucht
60 pro Stunde	je Konto für Einladungen und Einschreibungen mit E-Mail-Benachrichtigung
60 pro Minute	je IP-Adresse für Anfragen ohne gültige Zugangsdaten

Jede Antwort zeigt den aktuellen Stand des engsten geltenden 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. Auch Antworten mit Statuscode 403 tragen sie nicht: Die Prüfung der Zugriffsrechte läuft vor der Prüfung der Durchsatzbegrenzung.

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), bei 409 mit dem Fehlertyp IdempotencyKeyInUseError (die Sekunden aus Retry-After abwarten, dann mit demselben Idempotency-Key und demselben Body wiederholen) und bei 5xx-Fehlern (mit exponentiellem Backoff und einer begrenzten Zahl von Versuchen). Ergänzen Sie jede Wartezeit um eine kleine zufällige Verzögerung, damit nicht viele Clients im selben Moment wiederholen.
Wiederholen Sie POST-Anfragen mit einem Idempotency-Key, dann sind Wiederholungen auch nach Timeout oder Verbindungsfehler sicher: Idempotente Requests.
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.