WordPress REST API Error: 10 Fixes for 401, 403, 404, 500, Invalid JSON

Your WordPress block editor fails to save with "The response is not a valid JSON response." Or your headless CMS frontend stops syncing. Or a plugin that relies on the REST API stops working. Or you see cryptic errors: 401, 403, 404, 500.

The WordPress REST API powers the Gutenberg editor, most modern plugins, mobile apps, and headless WordPress setups. When it breaks, critical features stop working.

Here are the 10 most common REST API errors and the exact fix for each one.

What You Need to Know First

The WordPress REST API is an interface that lets applications (including the block editor) talk to your WordPress site by sending and receiving data in JSON format.

Test if your API is working: Open https://yourdomain.com/wp-json/ in your browser. You should see a JSON response (looks like structured text). If you see a 404, 403, or error, your API is broken.

Enable debug logging: If you're troubleshooting, add this to wp-config.php:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);

This creates a debug.log file at wp-content/debug.log with error details.

Error #1: "The response is not a valid JSON response" (Invalid JSON)

The problem: Gutenberg block editor won't save or publish. Banner shows "Updating failed. Error message: The response is not a valid JSON response."

Why it happens: The server returned something other than JSON ā€” usually an HTML error page (500 error), PHP warning, or the request was blocked. The block editor expects clean JSON back from the API, but it got garbage.

The fix:

Step 1: Save Permalinks (fixes 40% of cases instantly)

  1. Go to Settings > Permalinks.
  2. Don't change anything. Just click "Save Changes" twice.
  3. This flushes rewrite rules that might be broken.
  4. Try editing a post again.

Step 2: Test the API endpoint directly

  1. Open https://yourdomain.com/wp-json/ in an incognito browser window.
  2. If you see valid JSON (looks like structured data), API is working. Problem is elsewhere.
  3. If you see an error, 403, or HTML page, API is broken. Continue to Step 3.

Step 3: Disable all plugins

  1. Go to Plugins > Installed Plugins.
  2. Deactivate all plugins at once.
  3. Try editing a post.
  4. If it works, reactivate plugins one by one, testing after each one.
  5. When the error returns, you found the culprit plugin.

Step 4: Switch to default theme

  1. If plugins weren't the issue, go to Appearance > Themes.
  2. Switch to a default theme like Twenty Twenty-Four.
  3. Try editing a post again.
  4. If it works, your active theme or its functions.php is the problem.

Step 5: Check for output before the JSON

  1. Open /wp-json/ again in an incognito window.
  2. Look at the page source (Ctrl+U).
  3. If there's whitespace, text, or HTML BEFORE the JSON starts, that breaks it.
  4. Common culprits: BOM (Byte Order Mark) at the start of a PHP file, plugin outputting text before returning JSON, or security headers being added.
  5. Check wp-config.php and theme functions.php for accidental spaces or output before the opening <?php tag.

Expected result: Block editor saves normally. No more "Invalid JSON" error.

Error #2: 404 Not Found on REST API Endpoint

The problem: Visiting /wp-json/ returns 404. Or plugins say "REST API endpoint not found."

Why it happens: Permalink rewrites are broken. WordPress can't route requests to the API.

The fix:

Fix 1: Save Permalinks

  1. Go to Settings > Permalinks.
  2. Change the structure to anything other than "Plain" (Post Name is good).
  3. Click "Save Changes."
  4. Test /wp-json/ again.

Fix 2: Regenerate .htaccess (Apache)

  1. Go to Settings > Permalinks.
  2. Click "Save Changes" twice.
  3. This rewrites your .htaccess file with correct rules.
  4. If .htaccess is missing or corrupted, it recreates it.

Fix 3: Check Nginx rewrite rules (Nginx servers)

If you're on Nginx (not Apache), .htaccess doesn't apply. Contact your hosting provider and ask them to verify the Nginx location block includes REST API routes. Or check their documentation for WordPress on Nginx setup.

Fix 4: Check for URL prefix issues (multisite)

If using WordPress Multisite, the API path changes per site. If a subsite returns 404 on /wp-json/, it might be a path issue. Contact your host or check multisite documentation.

Error #3: 403 Forbidden on REST API

The problem: Browser shows "403 Forbidden" or "Access denied" when accessing /wp-json/ or API endpoints.

Why it happens: A security plugin, firewall, or server rule is blocking REST API access intentionally.

The fix:

Step 1: Disable security plugins temporarily

  1. Deactivate Wordfence, Sucuri, iThemes Security, or similar security plugins.
  2. Test /wp-json/ again.
  3. If it works, the security plugin blocked it.
  4. Go to the plugin's settings and whitelist /wp-json/ or re-enable with API allowed.

Step 2: Check firewall rules (Cloudflare, WAF)

  1. If using Cloudflare, go to Firewall > Rules.
  2. Look for rules blocking /wp-json/ paths.
  3. Disable or modify the rule to allow /wp-json/.

Step 3: Check mod_security (Hosting Provider)

  1. If hosting uses mod_security (ModSecurity), it might block JSON requests by default.
  2. Contact your hosting provider and ask: "Is mod_security blocking REST API requests?"
  3. They can whitelist /wp-json/ or disable the rule.

Step 4: Check for "block JSON" settings

  1. Some security plugins have an explicit "Block REST API requests" toggle.
  2. Go to your security plugin settings and check for this option.
  3. Make sure it's disabled (or set to allow authenticated requests).

Error #4: 401 Unauthorized

The problem: "401 Unauthorized" error when trying to make authenticated API requests or save posts.

Why it happens: Authentication credentials are missing, wrong, or expired. This commonly happens when using the REST API from external apps or mobile apps.

The fix:

For WordPress users editing posts (should not see 401):

  1. Log out and log back in in an incognito window.
  2. Clear browser cookies and cache.
  3. Try editing a post again.

For external apps connecting to REST API:

Use Application Passwords (recommended since WordPress 5.6):

  1. Go to Users > Your User Profile.
  2. Scroll to "Application Passwords."
  3. Enter an app name (e.g., "Mobile App" or "External Service").
  4. Click "Add New Application Password."
  5. Copy the generated password.
  6. In your external app, set Authorization Header to: Authorization: Basic [base64-encoded username:password]

Common 401 reasons:

  • Missing Authorization header
  • Invalid or expired credentials
  • Wrong username/password combination
  • Application Passwords disabled on the WordPress site
  • Proxy or reverse proxy stripping the Authorization header

Error #5: 405 Method Not Allowed

The problem: "405 Method Not Allowed" when trying to POST or PUT data to an API endpoint.

Why it happens: Your server or proxy is configured to only allow GET requests, not POST or PUT. Or the API endpoint doesn't accept that HTTP method.

The fix:

Fix 1: Contact hosting provider

Tell them: "REST API POST and PUT requests are returning 405 Method Not Allowed." They can check server configuration and enable those methods.

Fix 2: Check Nginx proxy settings

If using Nginx proxy, the upstream server might restrict methods. Ask your host to verify proxy_method settings.

Fix 3: Disable caching temporarily

  1. Some caching layers only allow GET requests.
  2. Disable cache plugins (WP Super Cache, etc.) temporarily.
  3. Test again.

Error #6: 500 Internal Server Error

The problem: "500 Internal Server Error" when accessing /wp-json/ or API endpoints.

Why it happens: PHP fatal error, database connection failure, or a plugin/theme throwing an exception when REST API loads.

The fix:

Step 1: Check debug.log

  1. Enable debug logging (see "What You Need to Know First" above).
  2. Try accessing /wp-json/ again to trigger the error.
  3. Go to wp-content/debug.log and look for the PHP error.
  4. The error message usually points to the exact line and plugin causing it.

Step 2: Disable all plugins

  1. Deactivate all plugins.
  2. Test /wp-json/ again.
  3. If it works, reactivate plugins one by one to find the culprit.

Step 3: Check database connection

  1. If disabling plugins doesn't help, the issue might be database connection timeout.
  2. Check that your database server is running.
  3. Verify database credentials in wp-config.php are correct.
  4. Contact your hosting provider if the database is down.

Step 4: Increase PHP memory/timeout

  1. Add to wp-config.php: define('WP_MEMORY_LIMIT', '256M');
  2. Add to .htaccess (Apache): php_value max_execution_time 300
  3. Restart PHP and test.

Error #7: Mixed Content (HTTP/HTTPS Mismatch)

The problem: Block editor works, but browser console shows "Blocked mixed content" errors. Or REST API calls fail with CORS or security warnings.

Why it happens: Your site is on HTTPS but REST API calls are trying to use HTTP (or vice versa). Or site URL settings don't match what the browser sees.

The fix:

  1. Go to Settings > General.
  2. Check both "WordPress Address (URL)" and "Site Address (URL)".
  3. Both should start with https:// if you have SSL.
  4. Both should be identical (same with/without www).
  5. Click Save Changes.
  6. Clear browser cache and try again.

Error #8: CORS (Cross-Origin) Error

The problem: External frontend (Next.js, React, etc.) connecting to WordPress REST API gets CORS errors.

Why it happens: Your frontend is on a different domain than WordPress, and WordPress doesn't allow cross-origin requests from that domain.

The fix:

Option 1: Use a CORS plugin

  1. Install and activate Allow REST API and Fetch plugin (or similar).
  2. Go to Settings and configure allowed origins.
  3. Add your frontend domain (e.g., https://frontend.com).
  4. Save.

Option 2: Add CORS headers manually

Add to wp-config.php or functions.php:

add_filter('rest_pre_serve_request', function() {
    header('Access-Control-Allow-Origin: *');
    header('Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS');
    header('Access-Control-Allow-Headers: Content-Type, Authorization');
    return false;
});

Option 3: Use a headless WordPress plugin

Plugins like WP Headless, Next.js WordPress plugin, or REST API extensions handle CORS automatically.

Error #9: 429 Too Many Requests (Rate Limiting)

The problem: "429 Too Many Requests" error when making rapid API calls.

Why it happens: WordPress or hosting provider has rate limiting enabled. Legitimate repeated requests are being throttled.

The fix:

Step 1: Add request delays

If it's your code making requests, add delays between calls to slow down the request rate.

Step 2: Check for aggressive security plugins

  1. Some security plugins aggressively rate-limit requests.
  2. Go to your security plugin settings and look for rate limiting options.
  3. Whitelist your IP or increase limits.

Step 3: Contact hosting provider

Ask if they have rate limiting on the server. They can increase limits or whitelist your IP.

Error #10: "REST API Disabled" / Custom Disabling

The problem: REST API works elsewhere but is deliberately disabled on your site (returns error or 403).

Why it happens: Someone added code to disable the REST API for security reasons. Common in custom functions.php or security hardening.

The fix:

Step 1: Search your code

  1. Go to Plugins > Plugin File Editor (or use SFTP).
  2. Search wp-config.php and active theme's functions.php for "rest".
  3. Look for code like: add_filter('rest_authentication_errors', ...);
  4. Delete or comment out that code.
  5. Save and test.

Step 2: Check for security hardening plugins

  1. Some security plugins have an option to "Disable REST API" for all users.
  2. Go to the plugin settings and disable this option.
  3. Allow REST API for authenticated users at minimum.

Step 3: Use Query Monitor for debugging

  1. Install Query Monitor plugin (free).
  2. Activate it.
  3. Try to access /wp-json/.
  4. Query Monitor will show the exact error and which plugin/hook caused it.

REST API Diagnostic Checklist

Before troubleshooting, run through this:

  1. ā˜ Test /wp-json/ in browser ā€” does it return JSON or an error?
  2. ā˜ Save Permalinks (Settings > Permalinks > Save Changes twice)
  3. ā˜ Clear browser cache and cookies
  4. ā˜ Disable all plugins, test, reactivate one by one
  5. ā˜ Switch to default theme (Twenty Twenty-Four), test
  6. ā˜ Enable WP_DEBUG and WP_DEBUG_LOG, check debug.log for errors
  7. ā˜ Check Site Health (Dashboard > Site Health) for warnings
  8. ā˜ Verify WordPress Address and Site Address match (Settings > General)
  9. ā˜ Test with incognito/private browser window
  10. ā˜ Contact hosting provider if 403, 404, or 500 persists

FAQ

Q: Does the REST API security risk my site?

A: No. By default, unauthenticated users can only read public posts. Writing requires authentication. But you can restrict access further if needed via security plugins.

Q: Will disabling all plugins slow down troubleshooting?

A: It sounds tedious, but it's the fastest way to find the culprit. Most REST API errors are plugin conflicts. Spend 10 minutes on this before diving into server logs.

Q: Should I use Classic Editor if REST API keeps failing?

A: No. Classic Editor bypasses REST API for editing, but plugins and headless setups will still break. Fix the REST API instead ā€” it's worth the 20 minutes.

Q: Is there a way to monitor REST API health?

A: Yes. WordPress Site Health (Dashboard > Site Health) checks REST API and shows warnings if it's broken. Query Monitor plugin also has REST API debugging.

The Real Talk

REST API errors feel obscure, but they're usually one of three things: (1) permalink rewrites are broken (Fix #1), (2) a plugin or theme is conflicting (deactivate/switch), or (3) a security tool is blocking it (whitelist). Start with those before spending hours in server logs. 80% of the time, saving permalinks or disabling plugins solves it in 5 minutes.

If you're building headless WordPress or a mobile app using REST API, use Application Passwords for authentication. It's secure, modern, and saves support tickets.