Fehlerbehandlung

Die vitalera-Gesundheits-API verwendet Standard-HTTP-Statuscodes und gibt strukturierte Fehlerantworten zurueck, um Ihnen zu helfen, Probleme in Ihrer RPM-Integration zu diagnostizieren und zu loesen. Ob Sie Vitalzeichen von Medizingeraeten erfassen oder klinische Workflows verwalten — eine konsistente Fehlerbehandlung gewaehrleistet einen zuverlaessigen Datenaustausch.

Fehlerantwortformat

Alle Fehlerantworten folgen einer konsistenten JSON-Struktur:

{
  "detail": "A human-readable description of the error.",
  "code": "error_code"
}

Fuer Validierungsfehler enthaelt die Antwort feldbezogene Details:

{
  "field_name": ["This field is required."],
  "nested_field": {
    "sub_field": ["Ensure this value is greater than 0."]
  }
}

Haeufige HTTP-Statuscodes

Client-Fehler (4xx)

Code	Bedeutung	Beschreibung
400	Bad Request	Der Anfragetext ist fehlerhaft oder es fehlen erforderliche Felder. Pruefen Sie die Antwort auf feldbezogene Validierungsfehler.
401	Unauthorized	Authentifizierung fehlgeschlagen. Das JWT-Token fehlt, ist abgelaufen oder ungueltig.
403	Forbidden	Der authentifizierte Benutzer hat keine Berechtigung, auf diese Ressource zuzugreifen oder diese Aktion auszufuehren.
404	Not Found	Die angeforderte Ressource existiert nicht oder der Benutzer hat keine Sichtbarkeit darauf.
422	Unprocessable Entity	Die Anfrage ist wohlgeformt, enthaelt aber semantische Fehler (z. B. ungueltiger Zustandsuebergang, Verstoss gegen Geschaeftsregeln).
429	Too Many Requests	Rate Limit ueberschritten. Siehe Rate Limits fuer Details zu Limits und Wiederholungsstrategien.

Server-Fehler (5xx)

Code	Bedeutung	Beschreibung
500	Internal Server Error	Ein unerwarteter Fehler ist auf dem Server aufgetreten. Wenn dies anhaelt, wenden Sie sich an den Support mit der Request-ID.
502	Bad Gateway	Ein nachgelagerter Service ist vorruebergehend nicht verfuegbar. Wiederholen Sie nach einer kurzen Verzoegerung.
503	Service Unavailable	Der Service befindet sich in Wartung. Ueberpruefen Sie die Statusseite fuer Updates.

Authentifizierungsfehler

Abgelaufenes Token

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid"
}

Loesung: Fordern Sie ein neues Access Token mit Ihrem Refresh Token oder Client-Zugangsdaten an. Siehe Authentifizierung.

Fehlendes Token

{
  "detail": "Authentication credentials were not provided."
}

Loesung: Fuegen Sie ein gueltiges JWT-Token im Authorization: Bearer <token>-Header ein.

Validierungsfehler

Validierungsfehler geben 400 Bad Request mit feldspezifischen Nachrichten zurueck:

{
  "status": ["\"invalid\" is not a valid choice."],
  "effective_period_start": ["This field is required."]
}

Loesung: Beheben Sie die angegebenen Felder und wiederholen Sie die Anfrage. Siehe die API-Referenz fuer gueltige Feldwerte.

Rate-Limit-Fehler

Wenn Sie das Rate Limit ueberschreiten, gibt die API 429 Too Many Requests zurueck:

{
  "detail": "Request was throttled. Expected available in 30 seconds."
}

Loesung: Warten Sie die in der Antwort oder im Retry-After-Header angegebene Dauer, bevor Sie es erneut versuchen. Siehe Rate Limits fuer Kontingentdetails.

Tipps zur Fehlerbehebung

1. Ueberpruefen Sie den Antwort-Body -- Fehlerantworten enthalten immer eine menschenlesbare detail-Nachricht.
2. Validieren Sie Ihr JWT -- verwenden Sie jwt.io, um Ihr Token zu dekodieren und dessen Ablauf (exp-Claim) zu ueberpruefen.
3. Ueberpruefen Sie Berechtigungen -- stellen Sie sicher, dass Ihre Anwendung oder Benutzerrolle Zugriff auf die angeforderte Ressource hat.
4. Ueberpruefen Sie das Anfrageformat -- vergleichen Sie Ihre Anfrage mit den API-Referenzbeispielen.
5. Pruefen Sie Rate Limits -- wenn Sie 429-Antworten erhalten, implementieren Sie exponentielles Backoff.
6. Kontaktieren Sie den Support -- bei anhaltenden 500-Fehlern kontaktieren Sie support@vitalera.io mit dem Anfragezeitstempel und Endpunkt.