EntwicklerREST API

Fehler

Die fepli-API nennt mit HTTP-Statuscodes, was schiefgelaufen ist, und erklärt es in einem JSON-Body im Format Problem Details. Die Erklärung ist für Menschen geschrieben und sagt, was Sie als Nächstes tun können.

Das Fehlerformat

Fehlerantworten haben den Content-Type application/problem+json. Ausgenommen ist ein abgelehntes Token: Dieses 401 hat einen leeren Body und nennt seinen Grund im Header WWW-Authenticate.

Name
type
Typ
string
Beschreibung
Eine URI-Referenz auf die Art des Problems, zum Beispiel /errors/409.
Name
title
Typ
string
Beschreibung
Eine kurze Zusammenfassung. Meist An error occurred.
Name
status
Typ
integer
Beschreibung
Der HTTP-Statuscode.
Name
detail
Typ
string
Beschreibung
Was in diesem Fall schiefgelaufen ist und oft auch, was Sie stattdessen tun können. Bei Validierungsfehlern steht je Problem eine Zeile da.
Name
violations
Typ
array
Beschreibung
Nur bei fehlerhaften Eingaben: ein Objekt je Problem, mit propertyPath, message und code. Siehe Schreibzugriffe.

409 Conflict

{
  "type": "/errors/409",
  "title": "An error occurred",
  "status": 409,
  "detail": "A paid receipt references this application. Reverse the receipt, or withdraw the application instead."
}

Statuscodes

Name
200 OK
Beschreibung
Die Anfrage war erfolgreich. Auch Aktionen wie Übergänge und Stornos antworten damit.
Name
201 Created
Beschreibung
Ein Datensatz wurde angelegt. Der Body enthält ihn.
Name
202 Accepted
Beschreibung
Die Anfrage wurde angenommen, und die Arbeit endet im Hintergrund, etwa beim Auffüllen einer Warteliste oder beim Entsperren einer E-Mail-Adresse. Der Body zeigt den Datensatz, wie er jetzt ist. Rufen Sie ihn etwas später erneut ab, um das Ergebnis zu sehen.
Name
204 No Content
Beschreibung
Ein Datensatz wurde gelöscht.
Name
400 Bad Request
Beschreibung
Ein Query-Parameter lässt sich nicht lesen, etwa ein fehlerhaftes Datum, ein Boolean, der weder true noch false ist, oder ein unbekannter status einer Anmeldung. Das detail nennt den Parameter. Korrigieren Sie die Anfrage. Eine Wiederholung hilft nicht.
Name
401 Unauthorized
Beschreibung
Kein gültiges Token: Es ist fehlerhaft, unbekannt oder abgelaufen, oder sein Inhaber ist deaktiviert. Der Body ist leer, siehe den Header WWW-Authenticate. Auch anonyme Anfragen an alles außer den öffentlichen Angeboten antworten damit. Siehe Authentifizierung.
Name
403 Forbidden
Beschreibung
Das Token ist gültig, darf das aber nicht tun: Es ist nur lesend und die Anfrage schreibt, oder seinem Inhaber fehlt die Rolle oder die Berechtigung für diese Aktion, zum Beispiel wenn eine Veranstalter:in ein veröffentlichtes Angebot ändert. Das detail nennt meist den Grund.
Name
404 Not Found
Beschreibung
Der Datensatz existiert nicht, oder Sie dürfen ihn nicht sehen. Die API unterscheidet das nicht. Auch eine für den Mandanten ausgeschaltete API antwortet damit.
Name
409 Conflict
Beschreibung
Die Aktion passt nicht zum aktuellen Status des Datensatzes: ein Übergang, der gerade nicht möglich ist, das Löschen von etwas, auf das ein bezahlter Beleg noch verweist, eine doppelt bezahlte Anmeldung. Das detail nennt, was stattdessen möglich ist.
Name
415 Unsupported Media Type
Beschreibung
Ein Request-Body wurde ohne Content-Type: application/json gesendet.
Name
422 Unprocessable Entity
Beschreibung
Der Request-Body ist ungültig: Ein Pflichtfeld fehlt, ein Wert liegt außerhalb des Bereichs, oder ein referenzierter Datensatz existiert nicht. Im detail steht je Problem eine Zeile.
Name
429 Too Many Requests
Beschreibung
Sie haben das Rate-Limit erreicht. Warten Sie, bevor Sie es erneut versuchen.
Name
500 Internal Server Error
Beschreibung
Auf dem Server ist etwas schiefgegangen. Versuchen Sie es später erneut. Hält der Fehler an, wenden Sie sich mit der Uhrzeit und der Anfrage an den Support.

Beispiele

Fehlerantworten

{
  "type": "/errors/400",
  "title": "An error occurred",
  "status": 400,
  "detail": "Unknown status \"paid\". Known: waiting, confirmed, waitlisted, rejected, withdrawn, unfulfilled, participated, noshow, email_unconfirmed, consents_outstanding."
}

Fehler behandeln

4xx außer 429: Senden Sie dieselbe Anfrage nicht erneut. Lesen Sie detail, korrigieren Sie die Anfrage oder die Daten und versuchen Sie es dann noch einmal.
409: Rufen Sie den Datensatz erneut ab. Seine transitions, sein status oder das Feld paid zeigen, was jetzt möglich ist.
429 und 5xx: Wiederholen Sie die Anfrage mit wachsendem Abstand, zum Beispiel nach 1, 2, 4 und 8 Sekunden.
Protokollieren Sie detail zusammen mit dem Status. So verstehen Sie am schnellsten, was passiert ist.