# Fehlerbehandlung und Wiederholungsversuche

### A. Überblick

Die Pipeline für Video-Upload und -Verarbeitung ist so konzipiert, dass sie robust und widerstandsfähig ist. In jedem Schritt – vom Hochladen der Datei bis zur abschließenden Videoanalyse – berücksichtigt das System potenzielle Fehler. Die Fehlerbehandlung ist auf mehreren Ebenen integriert, und automatische Wiederholungen werden dort implementiert, wo es sinnvoll ist. Dies stellt sicher, dass vorübergehende Fehler die Benutzererfahrung nicht unterbrechen und dass alle Fehler zu Diagnosezwecken protokolliert werden.

### B. Fehlerkategorien

**1. Clientseitige Fehler (HTTP 4xx)**

* **400 Bad Request:**
  * Tritt auf, wenn der Client fehlerhafte Daten sendet (z. B. fehlende erforderliche Felder wie `video` oder `user_id`, oder ein ungültiges Dateiformat).
  * Validierungsfehler bei Eingabefeldern (z. B. falscher Dateityp oder ein ungültiges Zeitstempelformat).
* **401 Unauthorized:**
  * Wird ausgelöst, wenn das Zugriffstoken fehlt oder ungültig ist.
* **403 Forbidden:**
  * Wird zurückgegeben, wenn einem Benutzer die erforderlichen Berechtigungen fehlen (z. B. ein Nicht-Administrator, der versucht, eine Sitzung im Namen eines anderen Benutzers zu erstellen).
* **404 Not Found:**
  * Tritt auf, wenn die angeforderte Ressource (wie eine bestimmte Sitzung oder Videodatei) nicht verfügbar ist.
* **422 Unprocessable Entity:**
  * Wird verwendet, wenn der Dateityp korrekt ist, aber nicht verarbeitet werden kann (z. B. Korruption der Videodatei, Verschlüsselungs-/Entschlüsselungsfehler).

**2. Serverseitige Fehler (HTTP 5xx)**

* **500 Internal Server Error:**
  * Erfasst unerwartete Probleme während der Backend-Verarbeitung, wie unbehandelte Ausnahmen in Videoverarbeitungsmodulen.
* **503 Service Unavailable:**
  * Zeigt eine vorübergehende Nichtverfügbarkeit des Dienstes an, möglicherweise aufgrund hoher Last oder Wartung.

### C. Wiederholungsstrategie

**1. Automatischer Wiederholungsmechanismus**

Für vorübergehende Fehler – insbesondere Netzwerkprobleme oder temporäre Backend-Überlastung – implementiert das System eine **exponentielle Rückzugs**-Wiederholungsstrategie:

* **Wiederholungsauslöser:**
  * Netzwerkzeitüberschreitungen, Verbindungsabbrüche, HTTP 503-Fehler oder 500-Fehler, die auf einen temporären Fehler hinweisen.
* **Wiederholungsrichtlinie:**
  * Der Client (oder der Verarbeitungsdienst selbst) wird den fehlgeschlagenen Vorgang automatisch bis zu einem Maximum von 3–5 Mal wiederholen.
  * Die Verzögerungen zwischen den Wiederholungen erhöhen sich exponentiell (z. B. 1 Sekunde, 2 Sekunden, 4 Sekunden), um eine Überlastung des Backends zu vermeiden.
* **Schutzschalter:**
  * Wenn ein bestimmter Endpunkt konstant über die maximale Anzahl von Wiederholungen hinaus fehlschlägt, öffnet das System einen Schutzschalter, um die Wiederholungen vorübergehend zu stoppen, den Fehler zu protokollieren und das Überwachungssystem zu alarmieren.

**2. Manuelle Eingriffe und Rückfalloptionen**

* **Rückfalloptionen:**
  * In Fällen, in denen eine Videodatei nach allen Wiederholungen nicht verarbeitet werden kann, greift das System auf eine generische Fehlermeldung zurück (mit der Option, den Upload manuell neu zu starten) und speichert die Fehlerdetails für den Support.
* **Benutzerfeedback:**
  * Die API gibt klare Fehlermeldungen und Fehlercodes zurück, die vom Frontend genutzt werden können, um Benutzer zu informieren (z. B. „Upload aufgrund von Netzwerkproblemen fehlgeschlagen. Bitte versuchen Sie es später erneut.“).
* **Protokollierung & Alarmierung:**
  * Alle Fehler – einschließlich derjenigen, die Wiederholungen auslösen – werden mit Details (Fehlermeldung, Zeitstempel, betroffene Ressource) protokolliert. Diese Informationen dienen dem Debugging und können Alarme für kritische Probleme auslösen.

### D. Implementierungsdetails

* **Format der Fehlerantwort:**\
  Jede Fehlerantwort enthält eine konsistente JSON-Struktur:

```
{
  "error": "Detailed error message describing what went wrong.",
  "error_code": "SPECIFIC_ERROR_CODE"
}
```

* **Statuscode-Zuordnung:**\
  Jeder Endpunkt in der API ist so konfiguriert, dass er spezifische HTTP-Statuscodes für erwartete Fehlerszenarien zurückgibt.
* **Überwachung & Analytik:**\
  Unser Backend überwacht kontinuierlich Fehlerraten und Wiederholungsversuche, um Schwellenwerte automatisch anzupassen und das Ingenieurteam über potenzielle Probleme zu informieren.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aikynetix.app/de/api-documentation/video-upload-and-processing-workflow/error-handling-and-retries.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.