8.1 Allgemeines

Der MCDMS WebService verwendet standardisierte HTTP-Statuscodes, um das Ergebnis einer Anfrage zurückzugeben.

Jede Anfrage endet mit einem eindeutigen Statuscode, anhand dessen der aufrufende Client erkennen kann, ob die Verarbeitung erfolgreich war oder weshalb sie fehlgeschlagen ist.

Zusätzlich sollten Clients den Antworttext protokollieren, um Fehler später nachvollziehen zu können.

8.2 Übersicht der HTTP-Statuscodes

Statuscode	Bezeichnung	Bedeutung
200	OK	Anfrage erfolgreich verarbeitet
400	Bad Request	Ungültige Anfrage oder fehlende Parameter
401	Unauthorized	API-Key fehlt oder ist ungültig
403	Forbidden	Zugriff auf die angegebene IK nicht erlaubt
404	Not Found	Datei oder Endpunkt nicht gefunden
409	Conflict	Datei existiert bereits
413	Payload Too Large	Maximale Dateigröße überschritten
500	Internal Server Error	Interner Fehler im WebService

8.3 HTTP 200 – OK

Die Anfrage wurde erfolgreich verarbeitet.

Typische Ursachen

• Datei erfolgreich hochgeladen
• Datei erfolgreich heruntergeladen
• Datei erfolgreich gelöscht
• Dateiliste erfolgreich erstellt
• Status-Endpunkt erfolgreich aufgerufen

Beispiel

HTTP/1.1 200 OK

8.4 HTTP 400 – Bad Request

Die Anfrage konnte aufgrund fehlerhafter oder unvollständiger Angaben nicht verarbeitet werden.

Typische Ursachen

• Header fehlt
• Dateiname fehlt
• IK fehlt
• Ungültiges Anfrageformat
• Fehlerhafte URL

Lösung

• Header prüfen
• Dateiname prüfen
• URL prüfen
• Dokumentation vergleichen

8.5 HTTP 401 – Unauthorized

Der API-Key konnte nicht erfolgreich geprüft werden.

Typische Ursachen

• Header X-API-KEY fehlt
• API-Key falsch
• API-Key ungültig
• API-Key abgelaufen (falls verwendet)

Beispiel

HTTP/1.1 401 Unauthorized

Lösung

• API-Key prüfen
• Schreibfehler ausschließen
• Konfiguration kontrollieren

8.6 HTTP 403 – Forbidden

Der API-Key ist gültig, jedoch darf auf die angegebene IK nicht zugegriffen werden.

Typische Ursachen

• IK nicht freigegeben
• Falsche IK angegeben
• IK nicht in der Konfiguration enthalten

Beispiel

HTTP/1.1 403 Forbidden

Lösung

• IK prüfen
• Freigabe in der appsettings.json kontrollieren

8.7 HTTP 404 – Not Found

Die angeforderte Ressource wurde nicht gefunden.

Typische Ursachen

• Datei existiert nicht
• Endpunkt falsch geschrieben
• Datei bereits gelöscht

Beispiel

HTTP/1.1 404 Not Found

Lösung

• Dateiname prüfen
• API-Endpunkt prüfen
• Dateiliste abrufen

8.8 HTTP 409 – Conflict

Die gewünschte Aktion kann aufgrund eines Konflikts nicht ausgeführt werden.

Typische Ursachen

• Datei mit gleichem Namen existiert bereits
• Überschreiben ist deaktiviert

Lösung

• Anderen Dateinamen verwenden
• Vorhandene Datei löschen
• Überschreiben aktivieren (falls unterstützt)

8.9 HTTP 413 – Payload Too Large

Die hochgeladene Datei überschreitet die zulässige Maximalgröße.

Typische Ursachen

• Datei zu groß
• MaxUploadBytes überschritten

Beispiel

HTTP/1.1 413 Payload Too Large

Lösung

• Datei verkleinern
• Konfiguration anpassen

8.10 HTTP 500 – Internal Server Error

Während der Verarbeitung ist ein interner Fehler aufgetreten.

Typische Ursachen

• Dateisystem nicht erreichbar
• Schreibrechte fehlen
• Konfigurationsfehler
• Ausnahme im WebService

Beispiel

HTTP/1.1 500 Internal Server Error

Lösung

• Windows-Ereignisanzeige prüfen
• Logdateien auswerten
• NTFS-Berechtigungen prüfen
• Dienst neu starten

8.11 Typische Fehlersituationen

Problem	Ursache	Lösung
Upload funktioniert nicht	API-Key falsch	API-Key prüfen
Upload liefert 403	IK nicht freigegeben	IK konfigurieren
Download liefert 404	Datei nicht vorhanden	Dateiliste abrufen
Upload liefert 413	Datei zu groß	MaxUploadBytes erhöhen oder Datei verkleinern
Verbindung nicht möglich	Firewall blockiert	Firewallregel prüfen
HTTPS-Fehler	Zertifikat ungültig	Zertifikat erneuern
Dienst startet nicht	Konfigurationsfehler	appsettings.json prüfen

8.12 Vorgehensweise bei der Fehleranalyse

Bei Problemen empfiehlt sich folgende Reihenfolge.

1. Erreichbarkeit des WebService prüfen (/api/v1/status)
2. HTTPS-Zertifikat prüfen
3. API-Key kontrollieren
4. IK prüfen
5. Header prüfen
6. Dateiname kontrollieren
7. Logdateien auswerten
8. Windows-Ereignisanzeige prüfen
9. Windows-Dienst neu starten
10. Funktionstest erneut durchführen

8.13 Supportinformationen

Sollte ein Problem nicht behoben werden können, sollten folgende Informationen für den Support bereitgestellt werden.

Benötigte Information	Beispiel
Version des WebService	1.0.0
Betriebssystem	Windows Server 2025
Datum und Uhrzeit des Fehlers	24.07.2026 14:18
HTTP-Statuscode	403
Verwendeter Endpunkt	/api/v1/nachrichten
Verwendete IK	260820558
Logeintrag	Auszug aus der Protokolldatei
Beschreibung des Ablaufs	Kurze Fehlerbeschreibung

8.14 Checkliste zur Fehlerbehebung

Vor einer Supportanfrage sollten folgende Punkte überprüft werden.

Prüfung	Erledigt
WebService läuft	☐
Status-Endpunkt erreichbar	☐
HTTPS-Zertifikat gültig	☐
API-Key korrekt	☐
IK freigegeben	☐
Firewall freigegeben	☐
Datei vorhanden	☐
Header vollständig	☐
Logdateien geprüft	☐
Windows-Ereignisanzeige geprüft	☐