Fehlerbehandlung

HTTP-Statuscodes, Fehlerformate und Versionskonflikte in der SeminarPlan API.

• HTTP-Statuscodes
  • Erfolg
  • Client-Fehler
  • Server-Fehler
• Fehler-Response-Format
• Versionskonflikte (__v)
  • Wie es funktioniert
  • Konflikt-Response
  • Handling im Frontend
• Authentifizierungsfehler
  • Token abgelaufen
  • Fehlende Berechtigung
• Fehlerbehandlung im Frontend
  • Globaler Error Handler
  • API-Fehler in Stores
  • Fehler in V2-Programmen
• Soft Delete
• Siehe auch

HTTP-Statuscodes

Die API verwendet Standard-HTTP-Statuscodes:

Erfolg

Code	Bedeutung	Wann
200	OK	Erfolgreiche GET-, PATCH-, DELETE-Requests
201	Created	Erfolgreiche POST-Requests (neuer Eintrag)

Client-Fehler

Code	Bedeutung	Wann
400	Bad Request	Ungültige Parameter, fehlende Pflichtfelder, Validierungsfehler
401	Unauthorized	Kein oder ungültiges Token
403	Forbidden	Benutzer hat keine Berechtigung für diese Aktion
404	Not Found	Eintrag existiert nicht oder wurde gelöscht
409	Conflict	Versionskonflikt (siehe unten)
422	Unprocessable Entity	Semantisch ungültige Daten (z.B. doppelter Alias)
429	Too Many Requests	Rate-Limit überschritten

Server-Fehler

Code	Bedeutung	Wann
500	Internal Server Error	Unerwarteter Serverfehler
503	Service Unavailable	Server überlastet oder in Wartung

Fehler-Response-Format

Fehler werden als JSON zurückgegeben:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed: title is required"
}

Bei Validierungsfehlern kann eine detailliertere Struktur zurückkommen:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation failed",
  "validation": [
    { "field": "email", "message": "Ungültige E-Mail-Adresse" },
    { "field": "title", "message": "Titel ist ein Pflichtfeld" }
  ]
}

Versionskonflikte (__v)

SeminarPlan verwendet ein Versionierungsfeld (__v) auf jedem Dokument, um konkurrierende Änderungen zu erkennen.

Wie es funktioniert

1. Du lädst einen Eintrag - er hat z.B. __v: 3
2. Währenddessen ändert ein anderer Benutzer denselben Eintrag → __v: 4
3. Du sendest deine Änderung mit __v: 3
4. Der Server erkennt den Konflikt → 409 Conflict

Konflikt-Response

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Version conflict",
  "currentVersion": 4,
  "yourVersion": 3
}

Handling im Frontend

Das CRUD-Plugin (CrudPiniaPlugin) erkennt Versionskonflikte automatisch und zeigt einen Dialog:

• Überschreiben - Deine Änderungen erzwingen (sendet erneut mit aktuellem __v)
• Verwerfen - Deine Änderungen verwerfen und die aktuelle Version laden
• Vergleichen - Beide Versionen nebeneinander anzeigen

Optimistisches Locking

Zusätzlich zum __v-Feld nutzt SeminarPlan WebSocket-Locks (siehe WebSocket-Dokumentation), um Benutzer frühzeitig zu warnen, wenn jemand denselben Eintrag bearbeitet.

Authentifizierungsfehler

Token abgelaufen

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Token expired"
}

Das Frontend leitet bei einem 401-Fehler automatisch zum Login weiter.

Fehlende Berechtigung

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Im Frontend kannst du Berechtigungen vorab prüfen:

const { can } = useAcl();

// Prüfe, bevor du eine Aktion auslöst
if (!can('Booking', 'edit')) {
  // Button ausblenden oder deaktivieren
}

Fehlerbehandlung im Frontend

Globaler Error Handler

In der Produktion fängt ein globaler Error Handler unbehandelte Fehler ab und sendet sie an den ErrorService:

app.config.errorHandler = (err, instance, info) => {
  ErrorService.report(err, info);
};

API-Fehler in Stores

Das CRUD-Plugin behandelt API-Fehler automatisch:

• Netzwerkfehler → Toast-Nachricht "Verbindung fehlgeschlagen"
• Validierungsfehler (400) → Fehlermeldung im Dialog anzeigen
• Versionskonflikt (409) → Konflikt-Dialog
• Berechtigung (403) → Toast-Nachricht "Keine Berechtigung"

Fehler in V2-Programmen

In V2-Programmen mit TanStack Query:

import { useQuery } from '@tanstack/vue-query';

const { data, error, isError } = useQuery({
  queryKey: ['contacts'],
  queryFn: () => getV2('/contacts'),
});

// Fehler reaktiv anzeigen
if (isError.value) {
  console.error('API-Fehler:', error.value);
}

Soft Delete

SeminarPlan verwendet Soft Delete statt echtem Löschen:

Status	Bedeutung
published	Aktiv und sichtbar
draft	Entwurf, nicht öffentlich
archived	Archiviert, nur über Filter sichtbar
deleted	Soft-gelöscht, nur für Admins sichtbar

Ein DELETE-Request setzt den Status auf deleted. Permanentes Löschen ist nur über spezielle Admin-Endpunkte möglich.

Siehe auch

• API-Dokumentation - REST-Endpunkte und Authentifizierung
• WebSocket - Echtzeit-Events und Locking
• Berechtigungen - Berechtigungssystem im Detail