WordPress REST API wp-json 404: Rewrite or Missing Route?

When WordPress /wp-json/ returns 404, first determine whether the web server cannot route the pretty URL or WordPress’s REST router deliberately rejected a specific endpoint. Those failures can produce the same HTTP number but require different fixes. A server-generated HTML 404 at the REST root is not the same thing as a JSON error with code: rest_no_route.

Begin with the public, read-only REST index. Do not reset production rewrite rules, deactivate a firewall or register a new route until you can identify the layer that returned the failure.

1. Compare the pretty route with the documented fallback

The WordPress REST API handbook explains that the REST API root commonly appears at /wp-json/, while installations without pretty permalinks can use /?rest_route=/. Both routes are intended to reach the REST API index. For a site installed in a subdirectory, use the actual WordPress site base rather than copying a root-domain URL blindly.

For a public WordPress test domain, compare ordinary GET responses:

curl --silent --show-error --max-time 15 \
  --dump-header - https://example.com/wp-json/ \
  --output /tmp/wp-rest-pretty.json

curl --silent --show-error --max-time 15 \
  --dump-header - 'https://example.com/?rest_route=/' \
  --output /tmp/wp-rest-fallback.json

Check the HTTP status, Content-Type, final redirect destination and whether the body contains a plausible REST route index. These are anonymous read-only requests; no session cookie, password or elevated REST capability is needed. The fallback is a diagnostic tool, not an argument to leave rewrite rules broken.

2. Separate the actual response types

3. If the fallback works, inspect rewrite ownership

WordPress’s core REST rewrite function adds rules routing REST URLs to the rest_route query variable. If the query-string fallback works while the pretty path returns a server 404, inspect which software is supposed to rewrite the URL: Apache, Nginx, a hosting-panel configuration or a reverse proxy. A custom Nginx vhost does not use .htaccess; editing that file will not fix an Nginx-only routing problem.

In a controlled environment, inspect Settings → Permalinks and the host’s published, version-appropriate rewrite configuration. Saving the permalink screen can regenerate WordPress rewrite rules, so it is a change operation—not a completely read-only diagnostic. Record the previous settings, use a staging replica when possible and verify other front-end URLs afterward. Do not paste an unknown rewrite template over a working commerce site’s custom configuration.

A WordPress.org support exchange describes permalink regeneration as one possible remedy, but that recommendation is not proof that it will fix a missing endpoint on another server.

4. If REST JSON says rest_no_route, check endpoint identity

The REST routes and endpoints guide explains that a route’s HTTP methods and its namespace are part of its identity. The root discovery index may work while a request to /wp-json/vendor/v1/action fails because that endpoint was never registered, its owning plugin is inactive, its API namespace/version changed, or the wrong method was used. A GET request cannot test a POST-only action merely by opening it in a browser.

For a read-only route, inspect official documentation and the route index if exposed. Do not send guessed POST, PUT, DELETE or payment-related requests to discover methods on production. In a plugin development environment, inspect the code that calls register_rest_route(), its registration hook and the plugin’s active/version state. Re-saving permalinks cannot register a missing callback.

If a privileged route responds 401 or 403 rather than 404, consult the Site Health REST permissions guide before changing access policy. Correct authorization should not be misclassified as a broken REST endpoint.

5. Identify proxy, cache and security interference

Compare origin and public responses through approved administrator access, without exposing private origin addresses or disabling TLS verification for real users. A CDN may return a cached HTML 404, route /wp-json/ to another application or challenge an automated request. Log a request ID, timestamp, actual path and host to correlate the decision with trusted CDN and web-server records.

Apply only a verified, narrow correction to the right owner: permalink rules, the specific virtual host, proxy location block, or a documented plugin route. Globally allowlisting /wp-json/ or disabling REST authentication to get HTTP 200 can create security and business risk.

6. Verify the route and the real user workflow

After an approved change, read the REST index via both routes and confirm that the intended safe endpoint gives the expected status and JSON schema. Then test the exact application feature that originally failed, with its intended identity and HTTP method, using a safe staging workflow. Check private logs and unrelated WordPress front-end routes for regressions.

When both routes time out instead of returning 404, use the loopback timeout guide if WordPress’s own server request is failing. If the issue is about a machine client fetching an ordinary public page, use the robots and sitemap discovery audit rather than editing REST routes. For a verified WordPress hosting or routing defect, ModelGain WordPress Development provides an implementation-oriented next step.