Error Handling

Fehlerstruktur

Die LIVOI API verwendet für Fehler ein einheitliches JSON-Schema. Clients können dadurch Status, Fehlermeldung und Detailursachen konsistent auswerten.

Die Fehlerrückgabe umfasst:

status_code: HTTP-Statuscode als String
status_message: textuelle Beschreibung aus dem HTTP-Status, z. B. Forbidden oder Unprocessable Entity
errors: Liste mit Error-Objekten

Ein Error-Objekt kann diese optionalen Felder enthalten:

info
type
context
cause

cause kann ein einzelnes Objekt oder eine Liste sein. Bei Validierungsfehlern wird typischerweise eine Liste erzeugt. Cause-Einträge können details, value, location und code enthalten.

Minimalbeispiel

{
  "status_code": "403",
  "status_message": "Forbidden",
  "errors": [
    {
      "info": "Missing permission for agents.read."
    }
  ]
}

Validierungsfehler

HTTP 422 ist bei Pydantic-Feldvalidierung und Dynamic Query häufig. Die Statusphrase lautet aktuell Unprocessable Entity.

{
  "status_code": "422",
  "status_message": "Unprocessable Entity",
  "errors": [
    {
      "info": "Validation failed.",
      "type": "ValidationError",
      "cause": [
        {
          "details": "Input should be greater than or equal to 1",
          "value": 0,
          "location": ["body", "page", "number"],
          "code": "greater_than_equal"
        }
      ]
    }
  ]
}

HTTP-Statuscodes

Code	Status	Beschreibung
200	OK	Standardantwort für erfolgreiche HTTP-Anfragen. Die Ressource wurde erfolgreich abgerufen oder verarbeitet.
201	Created	Die Anfrage war erfolgreich und eine neue Ressource wurde erstellt. Wird typischerweise bei POST-Anfragen verwendet.
204	No Content	Die Anfrage war erfolgreich, aber es gibt keinen Inhalt zurückzugeben. Häufig bei DELETE-Operationen.

Code	Status	Beschreibung
400	Bad Request	Die Anfrage war fehlerhaft oder unvollständig. Überprüfe Parameter, Filter oder das JSON-Format.
401	Unauthorized	Authentifizierung ist erforderlich und fehlgeschlagen oder wurde nicht bereitgestellt.
403	Forbidden	Der Zugriff auf die angeforderte Ressource wurde verweigert, z. B. wegen fehlender Berechtigungen.
404	Not Found	Die angeforderte Ressource konnte nicht gefunden werden.
409	Conflict	Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource.
422	Unprocessable Entity	Die Anfrage konnte syntaktisch verarbeitet werden, enthält aber semantische Fehler oder ungültige Felder.
429	Too Many Requests	Der Client hat zu viele Anfragen in kurzer Zeit gesendet.

Code	Status	Beschreibung
500	Internal Server Error	Ein unerwarteter Fehler ist auf dem Server aufgetreten.
503	Service Unavailable	Der Server ist vorübergehend nicht verfügbar, z. B. wegen Wartung oder Überlastung.

Für Dynamic Query sind in den Route-Spezifikationen insbesondere 400, 401, 403, 404, 422 und 500 hinterlegt.