HTTP-4xx-Clientfehler: Bedeutung, Diagnose und Lösungen

Was dieser Fehler bedeutet und wie du ihn erkennst

Ein Browser, API-Client oder eine automatisierte Anfrage erhält einen HTTP-Statuscode zwischen 400 und 499. Die Antwort kann eine kurze Fehlerseite, ein JSON-Fehlerobjekt, erklärende Header oder keinen verwertbaren Body enthalten.

Häufige sichtbare Antworten sind:

• 400 Bad Request: Der Server kann die Anfrage in der empfangenen Form nicht verarbeiten.
• 401 Unauthorized: Die Authentifizierung fehlt, ist ungültig oder für die Ressource erforderlich.
• 403 Forbidden: Die Anfrage wurde verstanden, der Zugriff ist jedoch nicht erlaubt.
• 404 Not Found: Die angeforderte Ressource oder Route wurde nicht gefunden.
• 405 Method Not Allowed: Die Ressource unterstützt die verwendete HTTP-Methode nicht.
• 409 Conflict: Die Anfrage steht im Konflikt mit dem aktuellen Zustand der Ressource.
• 410 Gone: Die Ressource ist absichtlich nicht mehr verfügbar.
• 413 Content Too Large: Der Request-Body überschreitet ein konfiguriertes oder dokumentiertes Limit.
• 429 Too Many Requests: Der Client hat ein Rate-Limit oder Kontingent überschritten.

Derselbe Status kann unterschiedlich aussehen, je nachdem, ob er von der Anwendung, einem Reverse Proxy, CDN oder einer Web Application Firewall erzeugt wurde.

Hauptursachen nach Wahrscheinlichkeit

Häufige Ursachen in diagnostischer Reihenfolge

1. Fehlerhafte oder ungültige Anfrage — 400: Ungültige Syntax, eine falsch codierte URL, ungültiges JSON, ein falscher Content-Type oder fehlende Pflichtdaten können die Verarbeitung verhindern.
2. Fehlende oder ungültige Authentifizierung — 401: Der Anfrage fehlen möglicherweise Zugangsdaten, sie enthält abgelaufene Zugangsdaten oder verwendet Zugangsdaten, die der Endpunkt nicht akzeptiert.
3. Unzureichende Berechtigung oder Sicherheitsrichtlinie — 403: Die Identität kann authentifiziert, aber nicht autorisiert sein. Alternativ können eine IP-Regel, ein CDN, eine WAF, ein Proxy oder eine Anwendungsrichtlinie den Zugriff verweigern.
4. Falsche Route oder falscher Ressourcenstatus — 404 oder 410: Die URL kann falsch sein, ein Deployment kann die Route nicht enthalten, eine Ressource kann verschoben worden sein oder der Betreiber kann sie absichtlich entfernt haben.
5. Nicht unterstützte HTTP-Methode — 405: Der Client verwendet GET, POST, PUT, PATCH oder DELETE, obwohl der Endpunkt eine andere Methode erlaubt.
6. Konflikt bei Status oder Version — 409: Die angeforderte Änderung kann mit dem aktuellen Ressourcenstatus, einem vorhandenen Objekt oder einer anderen Aktualisierung kollidieren.
7. Anfrage überschreitet ein Limit — 413: Der Body, Upload oder die codierte Anfrage ist größer als ein von der Anwendung oder einem zwischengeschalteten System erzwungenes Limit.
8. Zu viele Anfragen — 429: Der Client hat ein Rate-Limit, ein Parallelitätslimit oder ein Kontingent überschritten.

Ein CDN, eine WAF oder ein Reverse Proxy kann eine 4xx-Antwort erzeugen, bevor die Anfrage die Origin erreicht. In diesem Fall gehört der scheinbare Anwendungsfehler möglicherweise zu einer früheren Netzwerkschicht.

So behebst du den Fehler

1. Die exakte Antwort erfassen

Notieren Sie den numerischen Status, die vollständige URL, die HTTP-Methode, den Zeitpunkt, den Anfrage-Typ und relevante Response-Header. Bei API-Anfragen sollten Sie außerdem den bereinigten Content-Type, die Anfragegröße sowie eine Korrelations- oder Request-ID erfassen. Notieren oder teilen Sie keine Passwörter, API-Keys, Cookies oder Access-Tokens.

Vergleichen Sie die Antwort mit einer bekannten funktionierenden Anfrage, sofern eine solche vorhanden ist. Prüfen Sie, ob Body und Header der Antwort die Origin-Anwendung, den Proxy, das CDN oder die WAF erkennen lassen.

2. Den Anfragevertrag prüfen

Prüfen Sie bei 400 die URL-Codierung, erforderliche Parameter, die JSON- oder Formularsyntax, den Content-Type und Pflichtfelder. Stellen Sie sicher, dass der Client das für den Endpunkt dokumentierte Format sendet, statt die Servereinstellungen zu ändern.

Prüfen Sie bei 405 die für den Endpunkt erlaubten Methoden. Stellen Sie sicher, dass der Client keiner Weiterleitung folgt und keine browserorientierte URL für eine API-Operation verwendet. Prüfen Sie den Response-Header Allow, sofern dieser vorhanden ist.

Untersuchen Sie bei 409 den aktuellen Ressourcenstatus. Das Objekt kann bereits existieren, seit dem Auslesen geändert worden oder für den angeforderten Zustandsübergang nicht verfügbar sein. Befolgen Sie das Konflikt- oder Versionierungsverhalten der Anwendung, statt die Schreiboperation blind zu wiederholen.

3. Identität und Zugriff prüfen

Prüfen Sie bei 401, ob die Authentifizierung vorhanden und aktuell ist und im vom Endpunkt erwarteten Format gesendet wird. Beschaffen Sie über den vorgesehenen Prozess neue Zugangsdaten, wenn die bisherigen abgelaufen sind. Fügen Sie niemals Zugangsdaten in Tickets, Logs oder Troubleshooting-Befehle ein.

Bestätigen Sie bei 403, dass die authentifizierte Identität über die erforderliche Rolle oder Ressourcenberechtigung verfügt. Websitebetreiber sollten Autorisierungsregeln, IP-Einschränkungen, WAF- oder CDN-Richtlinien sowie umgebungsspezifische Zugriffskontrollen prüfen. Ein 403 wird nicht durch eine URL-Änderung behoben, sofern nicht die URL selbst eine Richtlinienregel ausgelöst hat.

4. Routing und Ressourcenstatus prüfen

Prüfen Sie bei 404 Schreibweise, Groß- und Kleinschreibung, sofern relevant, Pfadpräfixe, Hostnamen, Deployment-Umgebung und das Verhalten am Ende des Pfads. Prüfen Sie das Anwendungs-Routing, die Weiterleitung durch den Reverse Proxy und ob die Ressource tatsächlich existiert.

Betrachten Sie 410 als Signal für eine absichtliche Entfernung, sofern der Betreiber nichts anderes bestätigt. Aktualisieren Sie Links oder Clients auf die Ersatzressource, falls eine solche existiert. Wiederholen Sie nicht einfach dieselbe URL.

5. Anfragegröße prüfen

Messen Sie bei 413 den Request-Body oder Upload und vergleichen Sie ihn mit den dokumentierten Limits. Prüfen Sie jede relevante Schicht – Client, Reverse Proxy, CDN/WAF und Anwendung –, da das kleinste Limit die Antwort erzeugen kann. Reduzieren Sie zunächst die Payload oder verwenden Sie den dokumentierten Upload-Mechanismus.

Das Anheben eines Limits erfordert eine Genehmigung, eine Kapazitätsprüfung und koordinierte Konfigurationsänderungen. Dadurch können Ressourcenverbrauch und Angriffsfläche für den Missbrauch großer Anfragen steigen.

6. Rate-Limits sicher behandeln

Stoppen Sie bei 429 unnötige Wiederholungen, reduzieren Sie Parallelität und Anfragefrequenz und beachten Sie Retry-After, sofern vorhanden. Verwenden Sie, wo sinnvoll, begrenztes exponentielles Backoff und clientseitiges Caching.

Websitebetreiber sollten den Geltungsbereich des Limits ermitteln – Benutzer, Token, IP, Route oder Service – und die Kontingentkonfiguration sowie Verkehrsmuster prüfen, bevor sie das Limit ändern.

7. Antwortgebende Schicht ermitteln

Websitebetreiber sollten Zeitpunkt, Pfad, Methode und Request-ID mit den Logs von Anwendung, Reverse Proxy, CDN und Sicherheitssystemen abgleichen. Wenn für die Origin keine passende Anfrage vorliegt, untersuchen Sie zuerst CDN, WAF oder Proxy.

Vergleichen Sie Response-Header, Body-Format und Serverkennungen zwischen einem genehmigten direkten Origin-Test und dem öffentlichen Pfad. Umgehen Sie Sicherheitskontrollen nicht ohne Genehmigung.

8. Die konkrete Änderung erneut testen

Testen Sie erst erneut, nachdem Sie die Anfrage oder Regel geändert haben, die für die Antwort verantwortlich ist. Bestätigen Sie sowohl den erwarteten Erfolgsfall als auch relevante Fehlerfälle, etwa eine nicht autorisierte Identität, eine zu große Payload oder eine zu häufig gesendete Anfrage. Überwachen Sie nach Deployments oder Richtlinienänderungen die 4xx-Trends, um Regressionen zu erkennen.

Vorbeugung und Überprüfung der Lösung

• Dokumentieren Sie Endpunktmethoden, Pflichtfelder, Authentifizierungsanforderungen, Antwortcodes, Limits für die Anfragegröße und das Verhalten bei Rate-Limits.
• Halten Sie interne und externe Links aktuell und testen Sie Weiterleitungen oder Entfernungen, wenn sich Routen ändern.
• Verwenden Sie automatisierte Tests für Berechtigungsgrenzen, unterstützte Methoden, fehlerhafte Eingaben und Konflikte beim Ressourcenstatus.
• Prüfen Sie Anfragegrößen und das Wiederholungsverhalten von Clients vor dem Produktivstart.
• Verwenden Sie begrenztes Backoff, Caching und die Deduplizierung von Anfragen für Clients, bei denen 429-Antworten auftreten können.
• Überwachen Sie 4xx-Raten nach Route, Status, Client und antwortgebender Schicht, damit defekte Links, Berechtigungs-Regressionen und Client-Änderungen unterschieden werden können.
• Halten Sie Korrelations-IDs und bereinigte Logs über die Anwendungs-, Proxy-, CDN- und Sicherheitsschichten hinweg verfügbar.

Häufig gestellte Fragen