Fehler in Netzwerkverbindungen und APIs debuggen
Wenn dein Frontend nichts vom Backend bekommt, dein Mobile-App den Login nicht ausführen kann, oder die externe Zahlungs-API plötzlich Fehler liefert – das sind Netzwerk- und API-Bugs. Sie haben eine Eigenheit: das Problem kann überall liegen: in deinem Client-Code, im Server-Code, im Netzwerk dazwischen, in einer Firewall, in einem Proxy, im DNS, in der Lastverteilung.
Die gute Nachricht: es gibt eine Handvoll Werkzeuge die fast alle dieser Bugs aufdecken. Die wichtigsten: Browser-DevTools Network-Tab (für Frontend), curl (Kommandozeile), Postman/Insomnia (GUI für API-Tests), tcpdump/Wireshark (Paket-Ebene). Diese Lektion zeigt sie systematisch. Grundlagen zum HTTP-Protokoll findest du in K42, OSI-Schichten in K20.
1) HTTP-Status-Codes verstehen
Der erste Schritt jedes API-Debuggings: was war der HTTP-Statuscode? Die Antwort grenzt das Problem in wenige Sekunden ein. Klassifizierung:
Die wichtigsten konkreten Codes:
| Code | Bedeutung | Typische Ursache |
|---|---|---|
| 200 | OK | Alles gut |
| 201 | Created | POST erfolgreich, Ressource angelegt |
| 204 | No Content | Erfolg, aber leerer Response (z.B. DELETE) |
| 301/302 | Redirect | URL hat sich geändert |
| 400 | Bad Request | Du hast Müll geschickt, JSON ungültig, Pflichtfeld fehlt |
| 401 | Unauthorized | Token fehlt oder ungültig. „Wer bist du?" |
| 403 | Forbidden | Token okay, aber du darfst das nicht. „Du, aber nein." |
| 404 | Not Found | URL existiert nicht / Ressource gelöscht |
| 405 | Method Not Allowed | POST gegen einen GET-only Endpoint |
| 409 | Conflict | Optimistic Locking-Konflikt, doppelte Anlage |
| 422 | Unprocessable Entity | Syntax ok, aber semantisch falsch |
| 429 | Too Many Requests | Rate Limit überschritten |
| 500 | Internal Server Error | Server-Code crashte. Server-Logs lesen! |
| 502 | Bad Gateway | Proxy/LB konnte Backend nicht erreichen |
| 503 | Service Unavailable | Server überlastet oder wartungsmäßig down |
| 504 | Gateway Timeout | Backend antwortet zu langsam für den Proxy |
Die Unterscheidung 401 vs. 403 ist wichtig: 401 = „du hast dich nicht ausgewiesen" (Login fehlt), 403 = „du hast dich ausgewiesen, darfst aber nicht". Bei 401 → einloggen / Token erneuern. Bei 403 → falsche Rechte, andere User wählen oder Admin fragen.
2) Der Network-Tab in DevTools
Das wichtigste Tool für Frontend-API-Debugging: der Network-Tab in den Chrome/Firefox DevTools. Hier siehst du jeden einzelnen Request den deine Seite macht – mit Status, Größe, Dauer, Headers, Body. Erste Anlaufstelle bei „Login funktioniert nicht" oder „Daten kommen nicht an":
3) Die wichtigsten Network-Tab-Features
Im Network-Tab steckt mehr als nur Status-Anzeige. Diese Features solltest du kennen:
- Filter-Leiste oben: filtere nach Typ (XHR/Fetch, JS, CSS, Img, Doc...). „Fetch/XHR" für reine API-Calls ohne den ganzen Asset-Lärm.
- Disable Cache: Checkbox – Browser holt alles frisch. Wichtig beim Debuggen.
- Throttling: simuliert langsame Verbindung („Slow 3G"). Damit findest du UI-Bugs bei langsamen APIs.
- Preserve Log: Logs bleiben beim Page-Reload erhalten. Sonst werden sie gelöscht.
- Copy as curl: Rechtsklick auf einen Request → „Copy as cURL". Kommando das den exakten Request via Kommandozeile reproduziert. Pflichtfeature für API-Debugging!
- Replay XHR: Rechtsklick → „Replay XHR". Schickt denselben Request nochmal – praktisch wenn Server-Bug erst beim zweiten Versuch passiert.
- Initiator: zeigt welche JS-Zeile den Request ausgelöst hat. Bei mysteriösen Requests („wer macht das?") sehr nützlich.
- Timing: zeigt detaillierte Phasen – Queueing, DNS, Connect, SSL, TTFB, Download. Damit findest du wo Latenz herkommt.
4) curl: das Schweizer Taschenmesser
curl ist ein Kommandozeilen-Tool zum HTTP-Senden. Funktioniert auf jedem System (auch Windows 10+). Mit curl kannst du jede API direkt aus dem Terminal ansprechen – ohne Frontend, ohne PowerShell-Klimmzüge:
Die wichtigsten Flags:
| Flag | Bedeutung |
|---|---|
-X METHOD | HTTP-Methode (GET, POST, PUT, DELETE, PATCH) |
-H "Key: Value" | Header setzen (mehrfach erlaubt) |
-d 'data' | Body senden (JSON, Form, etc.) |
-i | Response-Headers mit ausgeben |
-v | Verbose – zeigt Request UND Response komplett |
-k | SSL-Zertifikat-Check skippen (für Test-Server mit ungültigem Zert) |
-L | Redirects folgen |
-o file | Output in Datei speichern |
-w "%{time_total}" | Zeit-Messung |
Pro-Tipp: curl -v ist gold. Es zeigt jeden Header der gesendet und empfangen wird – inklusive Status-Zeile. Bei Debugging unverzichtbar. Bei sensiblen Daten: Werte vor dem Posten anonymisieren, nie Bearer-Tokens in Tickets oder Slack pasten.
5) Postman und Insomnia
Wer GUIs mag: Postman (Industriestandard) und Insomnia (leichtgewichtige Alternative) sind grafische API-Clients. Stärken:
- Collections: Requests sammeln, dokumentieren, teilen
- Environments: Variablen für Dev/Staging/Prod separat halten
- Auth-Helper: OAuth-Flows, Bearer-Token-Verwaltung
- Tests: JavaScript-Snippets die Responses automatisch validieren
- Mock-Server: simulieren APIs die noch nicht existieren
Für ein paar quick-and-dirty Requests: curl. Für strukturierte API-Tests die das Team teilt: Postman. Beide haben ihren Platz.
6) CORS-Fehler erkennen
Ein Frontend-Klassiker: die Browser-Konsole sagt CORS error. Was bedeutet das?
CORS (Cross-Origin Resource Sharing) ist eine Browser-Sicherheitsmaßnahme. Wenn dein Frontend auf app.firma.de läuft aber API auf api.firma.de – das sind verschiedene Origins. Der Browser blockiert standardmäßig solche Requests, außer der Server gibt explizit per CORS-Header die Erlaubnis.
Diagnose von CORS-Bugs:
- In der Browser-Konsole steht typisch: „Access to fetch at ... from origin ... has been blocked by CORS policy"
- Im Network-Tab siehst du oft einen Preflight-Request mit OPTIONS-Methode – das ist der Browser der vorher fragt „darf ich?"
- Wenn der OPTIONS-Request fehlschlägt oder die richtigen Headers fehlen: CORS-Error
Fix muss serverseitig passieren. Im Flask: flask-cors-Library nutzen. In Spring Boot: @CrossOrigin-Annotation. Bei Nginx: Header-Direktive. Im Client kannst du CORS nicht „umgehen" – außer mit einem Proxy.
7) DNS und Routing
Manchmal liegt's gar nicht an HTTP, sondern darunter. Klassische Vorgehensweise wenn „API antwortet nicht":
- ping api.firma.de – kommt überhaupt eine Antwort? Wenn nicht: Server down oder Firewall.
- nslookup api.firma.de – wird der Hostname richtig aufgelöst? DNS-Probleme sind häufiger als man denkt.
- traceroute api.firma.de – wo bleibt das Paket hängen? Häufiger Bug: VPN nicht korrekt, Route fehlt.
- telnet api.firma.de 443 oder nc -zv api.firma.de 443 – ist der Port offen? Firewall blockt vielleicht.
- openssl s_client -connect api.firma.de:443 – funktioniert SSL/TLS? Zertifikat gültig?
Diese Befehle hast du in K45 L4 und K24 Troubleshooting kennengelernt. Sie funktionieren auch hier, weil API-Probleme oft Netzwerk-Probleme sind.
8) Wireshark und tcpdump
Wenn alle anderen Tools versagen: ans Paket. Wireshark (GUI) und tcpdump (CLI) zeigen den rohen Netzwerkverkehr auf Paket-Ebene. Bei merkwürdigen Bugs (TLS-Handshake scheitert, Pakete kommen in falscher Reihenfolge, MTU-Probleme) sind sie unschlagbar:
Wireshark öffnet diese .pcap-Files und visualisiert sie schön. Mit den richtigen Filtern findest du jedes Paket. Aber Achtung: bei verschlüsseltem TLS-Traffic (HTTPS) siehst du nur die TCP-Verbindung selbst, nicht die HTTP-Daten. Dafür braucht man entweder mitmproxy oder Server-seitig die TLS-Keys.
9) Häufige API-Bug-Patterns
Patterns die du in der Praxis ständig sehen wirst:
- Trailing slash matters:
/api/usersund/api/users/sind manchmal verschieden, oft via Redirect (301). Bei POST mit Body kann das stark verwirren. - Falsches Content-Type: Server erwartet JSON, du schickst Form-Data. Status meist 415 Unsupported Media Type.
- Zeitzonen-Mismatch: Client schickt Datum in lokaler Zeit, Server erwartet UTC. Plötzlich sind alle Termine 2 Stunden verschoben.
- Cache-Bugs: GET-Response wird gecached, neue Daten kommen nicht durch. Header:
Cache-Control: no-storebei dynamischen Daten. - JSON-Encoding-Probleme: Umlaute kaputt → falsche Content-Type-Charset-Angabe.
- Auth-Token abgelaufen: 401 obwohl du eingeloggt bist. Refresh-Token-Flow nicht implementiert.
- Rate Limiting: bei vielen Requests plötzlich 429. Retry-After-Header beachten.
- Race Conditions: zwei Requests gleichzeitig, einer überschreibt den anderen. Bei DB Optimistic Locking implementieren.
10) WebSocket und Streaming
Klassische HTTP-Requests sind „eine Frage, eine Antwort". Bei WebSockets, Server-Sent Events oder HTTP-Streaming bleibt die Verbindung offen, Daten fließen kontinuierlich. Debugging ist anders:
- DevTools Network-Tab hat einen WS-Filter mit eigener Ansicht der Messages
- Bei Verbindungs-Abbrüchen: Close-Codes prüfen (1000 = normal, 1006 = abnormal, 1011 = server error)
- Ping/Pong-Mechanismen prüfen – manche Proxies cancellen Idle-Connections
- Bei Server-Sent Events sieht man die Stream-Daten ähnlich
11) Mock-Server für Frontend-Entwicklung
Sehr produktive Technik: wenn dein Backend noch nicht fertig ist oder du es nicht erreichst – baue einen Mock-Server. Tools wie JSON Server (Node), Mockoon (GUI), WireMock (Java) oder einfach Postman-Mocks geben dir einen lokalen Fake-Server der vorhersehbare Antworten liefert. Dein Frontend redet damit – du kannst alle Edge-Cases (404, 500, leere Listen) gezielt provozieren ohne dass du dafür den echten Server kaputt machen musst.
12) Logging an beiden Seiten
Bei API-Bugs ist Logging doppelt wichtig: am Client UND am Server. Wenn ein Request schiefgeht, willst du beide Seiten der Geschichte. Correlation-IDs sind hier essentiell – eine Header-ID die der Client mit jedem Request sendet, der Server in seinen Logs verwendet. So kannst du Frontend-Log und Backend-Log derselben Aktion zuordnen.
Zusammenfassung
API-Debugging-Werkzeuge: Network-Tab (Frontend-Standard), curl (CLI universell), Postman/Insomnia (GUI mit Collections), tcpdump/Wireshark (Paket-Ebene). HTTP-Status-Klassen: 2xx Success, 3xx Redirect, 4xx = Client-Fehler (du!), 5xx = Server-Fehler (Backend!). Wichtige Codes: 401 (nicht authentifiziert), 403 (authentifiziert aber kein Recht), 404, 500, 502/504 (Proxy/Timeout). Network-Tab-Features: Filter, Throttling, „Copy as cURL", Replay, Initiator, Timing. CORS-Errors: Server muss Access-Control-Allow-Origin setzen – Frontend kann es nicht umgehen. Netzwerk-Layer-Bugs: ping, nslookup, traceroute, telnet, openssl s_client (siehe K24, K45 L4). Häufige Patterns: trailing slashes, Content-Type-Mismatch, Zeitzonen, Cache-Bugs, Token-Ablauf, Rate Limiting. WebSockets haben eigene Diagnose-Ansicht. Mock-Server für unabhängige Frontend-Entwicklung. Correlation-IDs verbinden Client- und Server-Logs.