Themeisle Docs

Appearance

Fix WordPress REST API 404 Errors and Redirects ​

Many WordPress plugin dashboards, theme options, and block editor screens rely on the REST API to load data and save changes. This guide helps you find out whether a REST API routing failure is the cause when a screen freezes, a button stays disabled, or a save action fails, and walks you through fixing it.

In this article

Identify a REST API Routing Failure ​

The WordPress REST API is the channel that plugin dashboards, the block editor, and some theme screens use to load data and save changes in the background, without reloading the page. When a request to this channel returns a 404 "not found" response or gets redirected to your homepage instead of the expected data, the screen making that request has no way to know what happened next. This can show up as:

  • A plugin dashboard or settings screen that freezes or never finishes loading.
  • Buttons or controls that stay disabled after an action is started.
  • A save action that fails, sometimes with an "invalid JSON response" or similar error.
  • A background status check (for example, tracking the progress of a long-running task) that never completes.

One example of this pattern is the Optimole error "An unexpected error occured while pulling the offloaded back to your site", which can appear during an image rollback. If you're troubleshooting Optimole's Image Storage rollback and see this message, or your rollback screen is frozen with controls disabled, this is one possible cause worth ruling out — but the message on its own doesn't confirm it. The same routing failure can also block a plugin from connecting to its remote service at all, or prevent a save action in an unrelated part of WordPress, such as saving a widget. Testing the REST API directly, as described below, is how you confirm whether this is the cause.

📝 Note: If your styling looks broken or a widget save fails specifically after an HTTP/HTTPS URL mismatch, see Styling Breaks, Invalid JSON Errors, or Failed Widget Saves (HTTP/HTTPS Mismatch) instead — that's a separate, more specific cause with its own fix.

Test the WordPress REST API ​

Before changing any settings, confirm whether the REST API is actually reachable on your site.

  1. Open a new browser tab and visit your site's REST API base endpoint: https://yoursite.com/wp-json/ (replace yoursite.com with your own domain).
  2. Check what you get back:
    • If the page displays a block of JSON text (data inside curly braces { }), the REST API base endpoint is reachable and working correctly.
    • If the page shows a 404 "not found" error, or redirects you to your homepage, the REST API is not being routed correctly.
  3. If /wp-json/ failed, test the alternate route: https://yoursite.com/?rest_route=/.
    • If this version returns JSON while /wp-json/ does not, the REST API itself is working, but the "pretty" URL rewrite path that turns /wp-json/ into a readable link is broken. This points you toward a permalink or web server rewrite problem rather than the REST API being completely disabled.
    • If both versions fail, the REST API is being blocked entirely rather than just mis-routed, and you should move on to checking security and hosting restrictions below.

Refresh WordPress Rewrite Rules ​

If /?rest_route=/ worked but /wp-json/ did not, WordPress's rewrite rules (the internal map that turns readable URLs into the requests your server understands) need to be rebuilt.

  1. From your WordPress dashboard, go to Settings > Permalinks.
  2. Without changing any options, click Save Changes. This rebuilds your site's rewrite rules.
  3. Test https://yoursite.com/wp-json/ again in your browser. It should now return JSON.
  4. Go back to the screen or action that was failing and try it again.

Check Security and Hosting Restrictions ​

If refreshing permalinks didn't fix it, or both /wp-json/ and /?rest_route=/ failed the first test, something between the browser and WordPress is blocking the request. This is commonly one of the following:

  • A security plugin on your site that blocks or restricts REST API access as part of its firewall or hardening features.
  • A redirect rule added by your theme, another plugin, or your .htaccess file (on Apache) or server configuration (on Nginx).
  • A hosting-level firewall or web application firewall (WAF) that filters requests before they reach WordPress.

To narrow this down:

  1. If you have a security plugin installed, check its settings for any option related to REST API access, firewall rules, or hardening, and temporarily adjust it to allow REST API requests. Test /wp-json/ again after each change.
  2. If you don't manage a security plugin yourself, or the REST API is still blocked afterward, contact your hosting provider. Ask them to:
    • Confirm that your site's permalink and rewrite rules are configured correctly at the server level (Apache .htaccess or Nginx configuration).
    • Check for any redirect rule that specifically affects wp-json requests.
    • Review their WAF or firewall logs for the exact REST API route and request method that failed, since a host can block a specific endpoint while leaving the rest of the REST API working.

⚠️ Warning: Only adjust security settings temporarily to test the fix. Don't leave firewall or security protection permanently disabled — re-enable it once you've confirmed which specific rule was causing the block, and keep only the adjustment needed to allow the REST API request in question.

Verify the Fix ​

Once you've made a change, confirm it worked before considering the issue resolved:

  1. Visit https://yoursite.com/wp-json/ again and confirm it returns JSON.
  2. Return to the plugin screen, editor, or save action that was originally failing, and try it again.
  3. Confirm the action completes without freezing, without leaving controls disabled, and without an error message.

If /wp-json/ now returns JSON but the original action still fails, the base REST API is working, but the specific route that action depends on may still be blocked. Hosts and security tools can filter individual REST API endpoints (for example, a route used only by one plugin) even while the base API responds normally. In that case, go back to your host or security plugin and ask them to check logs for that specific route and request method, rather than the REST API generally.

Was this helpful?