WordPress REST API liefert 404

Was dieser Fehler bedeutet und wie du ihn erkennst

• Beim Aufruf von /wp-json/ wird eine HTTP-404-Seite statt des JSON-Index der REST API angezeigt.
• Eine JavaScript-Anwendung, mobile App, ein REST-Client, Editor oder eine Integration meldet für eine WordPress-API-Anfrage 404 Not Found.
• Das WordPress-Frontend wird normal geladen, während REST-Anfragen fehlschlagen.
• ?rest_route=/ funktioniert, obwohl der lesbare Pfad /wp-json/ einen 404-Fehler zurückgibt.
• Der API-Index wird geladen, aber ein Plugin- oder benutzerdefinierter Endpunkt liefert 404.
• WordPress Site Health meldet, dass die REST API nicht verfügbar ist. Zur Ermittlung der Ursache müssen Antworttext und Statuscode weiterhin geprüft werden.

Hauptursachen nach Wahrscheinlichkeit

1. Veraltete oder fehlende Permalink-Rewrite-Regeln. Dies kommt häufig nach einer Migration, einer Änderung der Permalinks, einem Serverwechsel oder einer unvollständigen Bereitstellung vor.
2. Webserver oder Proxy leitet /wp-json/ nicht an WordPress weiter. Die Rewrite-Unterstützung von Apache, das try_files-Routing von Nginx, die Document-Root-Zuordnung oder die Einstellungen des virtuellen Hosts können fehlerhaft sein.
3. Eine Sicherheits-, Firewall-, CDN-, Cache- oder Hosting-Regel gibt 404 zurück. Einige Kontrollen verbergen blockierte Anfragen, indem sie „nicht gefunden“ statt „verboten“ zurückgeben.
4. Ein Plugin oder Theme verändert das REST-Verhalten. Es kann Routen entfernen, den Zugriff beschränken oder REST-Antworten filtern.
5. Nur ein benutzerdefinierter oder Plugin-Endpunkt ist fehlerhaft. Die Anfrage kann den falschen Namespace, die falsche Route, Version, HTTP-Methode oder Ressourcen-ID enthalten, oder die Route ist möglicherweise nicht registriert.
6. Die Anfrage zielt auf den falschen Installationspfad oder die falsche Website. Domainänderungen, Installationen in Unterverzeichnissen, Weiterleitungen, veraltete Anwendungseinstellungen und gecachte Antworten können dazu führen, dass Clients einen veralteten API-Basispfad verwenden.

So behebst du den Fehler

1. Umfang und Quelle des 404-Fehlers bestätigen

Notieren Sie den exakten Anfragepfad, HTTP-Status, Antworttext, Antwort-Header, die Anfragemethode und den Zeitstempel. Prüfen Sie, ob die Antwort von WordPress, dem Webserver, einem Reverse Proxy, einem CDN oder einer Sicherheitsschicht zu stammen scheint. Nehmen Sie keine Zugriffstokens, Cookies, Passwörter oder privaten Antwortdaten in Diagnoseaufzeichnungen auf.

Testen Sie den REST-API-Index unter /wp-json/ mit einem geeigneten Client. Wenn der Index JSON zurückgibt, aber ein Endpunkt 404 liefert, fahren Sie direkt mit Schritt 5 fort. Wenn der Index selbst 404 zurückgibt, machen Sie weiter.

2. WordPress-Rewrite-Regeln aktualisieren

Öffnen Sie im WordPress-Dashboard Einstellungen → Permalinks und klicken Sie auf Änderungen speichern, ohne die ausgewählte Permalink-Struktur zu ändern. Dadurch wird die Rewrite-Konfiguration von WordPress aktualisiert.

Testen Sie /wp-json/ erneut. Wenn die Deployment-Automatisierung oder ein Hosting-Control-Panel die Serverkonfiguration verwaltet, bestätigen Sie, dass die Rewrite-Einstellungen dauerhaft gespeichert und nicht beim nächsten Deployment überschrieben werden.

3. Lesbaren Pfad mit der Fallback-Route vergleichen

Testen Sie die REST API mit dem Query-Parameter-Fallback von WordPress: ?rest_route=/, angehängt an die normale Startseitenadresse der Website. Verwenden Sie das tatsächliche Schema, den Hostnamen und den Installationspfad. Bei einer Installation in einem Unterverzeichnis muss dieser Pfad möglicherweise Teil der Anfrage bleiben.

• Fallback funktioniert, aber /wp-json/ fehlschlägt: WordPress kann REST-Anfragen verarbeiten. Untersuchen Sie daher lesbare URL-Rewrites, Einstellungen des virtuellen Hosts, Proxy-Routing, die Document-Root-Zuordnung und Änderungen durch eine Migration.
• Beide Varianten fehlschlagen: Prüfen Sie Sicherheitskontrollen, das Front-Controller-Routing des Servers, das Verhalten von WordPress und Plugins sowie den konfigurierten Website- oder Installationspfad.
• Beide Index-Anfragen funktionieren, aber eine benutzerdefinierte Route fehlschlägt: Diagnostizieren Sie diesen Endpunkt gezielt in Schritt 5.

4. Webserver-, Proxy- und Sicherheits-Routing prüfen

Lassen Sie für Apache von einem autorisierten Administrator überprüfen, dass die Rewrite-Unterstützung für das WordPress-Verzeichnis aktiviert ist und die Rewrite-Regeln der Website in der Konfiguration des virtuellen Hosts vorhanden und zulässig sind. Prüfen Sie bei Nginx oder einem Reverse Proxy, ob Anfragen den WordPress-Front-Controller erreichen und /wp-json/ nicht als fehlende statische Datei behandelt wird.

Prüfen Sie die relevanten Aufzeichnungen in dieser Reihenfolge:

1. Zugriffs- und Fehlerprotokolle des Webservers für die fehlgeschlagene Anfrage.
2. CDN-, Load-Balancer- und Reverse-Proxy-Regeln sowie Cache-Einträge.
3. WordPress-Sicherheits-, Firewall-, Login-Schutz- und REST-Kontroll-Plugins.
4. WAF-Regeln auf Hosting-Ebene, die den Pfad, die Methode oder die Anfrage-Header als blockiert einstufen können.

Nehmen Sie jeweils nur eine kontrollierte Änderung vor, notieren Sie die ursprüngliche Einstellung und leeren Sie nach erfolgter Freigabe nur den relevanten Cache. Deaktivieren Sie eine Firewall oder ein Sicherheits-Plugin in der Produktionsumgebung nicht umfassend ohne einen genehmigten Wartungsplan. Wenn eine Sicherheitsregel verantwortlich ist, erlauben Sie den erforderlichen REST-Pfad und die benötigten Methoden gezielt, statt den gesamten Schutz zu umgehen.

5. Einen einzelnen fehlenden Endpunkt diagnostizieren

Bestätigen Sie den exakten Namespace, die Route, das Versionssegment, die HTTP-Methode, den abschließenden Pfadbestandteil und die Ressourcen-ID des Endpunkts. Vergleichen Sie die Anfrage mit der Routendokumentation oder dem Registrierungscode des Plugins oder der Anwendung.

Überprüfen Sie Folgendes:

• Das zuständige Plugin oder Theme ist in der getesteten Umgebung aktiv.
• Die Routenregistrierung wird während der REST-Initialisierung ausgeführt.
• Die Route verfügt über den erwarteten Permission Callback und wird für die aktuelle Anfrage nicht bedingt ausgelassen.
• Der Client verwendet den aktuellen API-Basispfad der Website und nicht eine alte Domain, ein altes Unterverzeichnis oder eine gecachte Anwendungseinstellung.
• Die angeforderte Ressource existiert tatsächlich. Ein fehlender Beitrag, Benutzer, ein fehlendes Produkt oder eine andere Ressource kann einen legitimen 404-Fehler auf Endpunktebene erzeugen, selbst wenn die REST API einwandfrei funktioniert.

Prüfen Sie, sofern verfügbar, den API-Index oder die Antwort der Routenermittlung. Wenn die erwartete Route fehlt, untersuchen Sie Registrierung, Plugin-Status, Namespace und umgebungsspezifische Konfiguration, statt das Problem als allgemeinen REST-Ausfall zu behandeln.

6. Nach jeder kontrollierten Änderung erneut prüfen

Testen Sie erneut mit einem Browser, einem autorisierten API-Client und, falls relevant, der Anwendung, die den Fehler gemeldet hat. Vergleichen Sie vor und nach jeder Änderung Statuscode, Antwort-Header, Antworttext und Herkunft der Antwort. Machen Sie vorübergehende Diagnoseänderungen rückgängig und dokumentieren Sie die endgültige Rewrite-, Firewall-, Cache-, Proxy- oder Plugin-Konfiguration.

Vorbeugung und Überprüfung der Lösung

• Fügen Sie einen REST-API-Smoke-Test für /wp-json/ und jeden geschäftskritischen benutzerdefinierten Endpunkt zu den Migrations- und Deployment-Prüfungen hinzu.
• Halten Sie Website-URL, Home-URL, Document Root und die Konfiguration von Unterverzeichnissen in allen Umgebungen konsistent.
• Verwalten Sie Rewrite-Konfiguration, Proxy-Regeln, Firewall-Richtlinien und Cache-Verhalten als dokumentierte Deployment-Einstellungen statt als undokumentierte Serveränderungen.
• Prüfen Sie Änderungen an Sicherheits-Plugins und WAFs auf ihre Auswirkungen auf authentifizierte und nicht authentifizierte REST-Anfragen.
• Überwachen Sie Status und Herkunft der Antwort bei wichtigen API-Aufrufen, damit ein von einem Proxy erzeugter 404-Fehler von einem von WordPress erzeugten 404-Fehler unterschieden werden kann.
• Dokumentieren Sie benutzerdefinierte Namespaces, Routen, unterstützte Methoden, das Berechtigungsverhalten sowie das für jeden Endpunkt verantwortliche Plugin oder Theme.