Antworten und Fehler
Der Umschlag jeder Antwort, das errors-Array, das immer mitkommt, die HTTP-Codes und was bei jedem zu tun ist, Validierungs- und Geschäftsmeldungen, die Sprache der Meldungen und entfernte Elemente.
Jede Antwort der API kommt im selben Umschlag. So reicht eine einzige Behandlung für alle Aufrufe.
Erfolg
{
"success": true,
"message": "Login successful.",
"data": { },
"pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}
pagination erscheint nur bei Listen. Siehe Paginierung.
Fehler
{
"success": false,
"message": "Valid email is required",
"errors": [{ "param": "email", "message": "Valid email is required" }]
}
- Das Array
errorskommt immer, auch bei nur einem Fehler. paramsagt, welches Feld den Fehler ausgelöst hat, sofern es eines gibt.messageist die Meldung zum Anzeigen.
So behandelst du Validierung und Geschäftsregel auf demselben Weg: Zeig errors[].message neben dem Feld param; ohne param oben.
Die zwei Fehlerarten
| Art | Beispiel | Woran du sie erkennst |
|---|---|---|
| Validierung | Ein Feld fehlt oder hat das falsche Format | 400, param = das Feld, kurze Meldung ("Title is required") |
| Geschäftsregel | Eine Aktion, die der aktuelle Zustand nicht zulässt | 400, 403, 404 oder 409, mit einer erklärenden Meldung („Unzureichendes Guthaben …“) |
Codes
| Code | Bedeutung | Was zu tun ist |
|---|---|---|
200 / 201 | Hat geklappt (201 beim Anlegen) | — |
204 | Hat geklappt, ohne Body (Löschungen) | — |
400 | Validierung fehlgeschlagen, oder X-CommunityId fehlt (errors[0].param = "X-CommunityId") | Lies errors und korrigiere |
401 | Token fehlt, ist ungültig oder abgelaufen | Neu anmelden |
402 | Die Zahlung wurde abgelehnt | Zeig der Käuferin die Meldung |
403 | Keine Berechtigung: Rolle reicht nicht, oder der Bereich schränkt ein, wer anlegen darf | Prüfe die Rolle und X-CommunityId |
404 | Existiert nicht, wurde entfernt, gehört zu einer anderen Community, oder der Pfad ist einer der alten mit /communities/{communityId}/ | Prüfe die ID, die Community und den Pfad |
409 | Konflikt mit dem aktuellen Zustand | Lies die Meldung |
429 | Zu viele Versuche (z. B. 10 ungültige Gutscheincodes in 15 Minuten) | Warte ein paar Minuten |
500 | Interner Fehler | Versuch es noch einmal; bleibt es dabei, schreib dem Support |
Echte Beispiele
| Situation | Antwort |
|---|---|
Produkte ohne den Header X-CommunityId auflisten | 400 · Gib die Community im Header X-CommunityId an., mit param: "X-CommunityId" |
| Bereich in einem Abschnitt anlegen, der nicht existiert | 400 · Abschnitt nicht gefunden oder gehört nicht zu dieser Community |
| Kursmodul in einem Kurs anlegen, der nicht existiert | 404 · Course not found |
| Mitglied veröffentlicht in einem Bereich „Team“ | 403 · Nur das Team (Admin, Inhaber, Moderator) kann diese Aktion ausführen |
| Administrator ändert einen Eigentümer | 403 · Nur ein Owner oder ein SuperAdmin kann einen Owner entfernen, herabstufen oder ändern. |
| Ein Zusatzprodukt mit Abonnenten aus einem Plan nehmen | 409 · Dieses Add-on kann nicht aus dem Tarif entfernt werden … |
Weitere Beispiele, in der Reihenfolge, in der sie beim Aufbauen auftreten, findest du unter Reihenfolge beim Anlegen.
Sprache der Meldungen
Die Meldungen kommen in der Sprache aus dem Header Accept-Language (pt-BR, en-US, es-ES, it-IT, de-DE und die übrigen Varianten). Einige Formatvalidierungen und ältere Meldungen antworten noch auf Englisch oder Portugiesisch.
Element einer anderen Community
Ein Element, das zu einer anderen Community gehört, antwortet mit 404, genau wie eine id, die es nicht gibt. Die API verrät nicht, dass das Element anderswo existiert: Für den Aufrufer gibt es es in der Community aus X-CommunityId nicht.
| Wann | Antwort |
|---|---|
Die Route nennt einen Bereich einer anderen Community (?spaceId=, der Bereich eines Kurses oder eines Call for Papers) | 404 · space.notFound |
| Die Route nennt ein Element einer anderen Community (einen Inhalt lesen, seine Kommentare, die Teilnehmenden einer Veranstaltung) | 404 · common.notFound |
| Inhalte, eine Veranstaltung oder einen Status einer anderen Community bearbeiten, löschen, kommentieren, darauf reagieren oder anheften | 404 · die Meldung des Moduls (content.notFound, event.notFound, status.notFound, course.notFound) |
Eigentümer, Administrator oder Moderator in einer Community zu sein, gibt keinen Zugriff auf etwas in einer anderen, auch nicht mit dem Header der eigenen. Gehört das Element zur Community und antwortet trotzdem mit 404, prüfe, ob X-CommunityId die richtige Community ist.
Entfernte Elemente
Die API löscht nicht wirklich: Gelöschte Elemente werden als entfernt markiert und erscheinen nicht mehr. Deshalb antwortet eine gelöschte ID mit 404, als hätte es sie nie gegeben.
Mit dem SDK
Das SDK wirft MemberfyError mit .status, .body (der ganze Umschlag) und .errors. Siehe JavaScript-SDK.