How to Debug WordPress REST API Errors: Complete Troubleshooting Guide

The WordPress REST API allows applications, plugins, themes, JavaScript, and external services to communicate with WordPress using HTTP requests.

It powers many features that users never see directly. WordPress itself uses the REST API for parts of the administration interface, while plugins and external applications can use it to retrieve posts, create content, update data, manage media, and build custom integrations.

When something goes wrong, however, REST API errors can be difficult to diagnose.

You might see a 401, 403, 404, or 500 response. A JavaScript application may simply report that a request failed. A plugin may show an error such as “The REST API encountered an error.” Or /wp-json/ may suddenly return an unexpected response.

The good news is that most WordPress REST API problems can be narrowed down systematically.

This guide explains how the WordPress REST API works, how to identify the type of error you are dealing with, how to test endpoints, and how to troubleshoot authentication, permalinks, plugins, themes, security systems, JavaScript, server configuration, and PHP errors.

What Is the WordPress REST API?

The WordPress REST API provides a way for applications to communicate with WordPress through HTTP requests.

WordPress exposes resources through routes and endpoints. For example, the standard posts endpoint is:

/wp-json/wp/v2/posts

A GET request can retrieve posts, while other HTTP methods can be used for actions such as creating or updating resources when the appropriate authentication and permissions are available. WordPress documents GET for retrieving data, POST for creating resources, PUT for updating resources, and DELETE for deleting resources.

The API uses JSON for requests and responses, including error responses. This makes it possible for browsers, applications, scripts, plugins, and external services to work with WordPress data in a predictable format.

How the WordPress REST API Works

A typical REST API request looks like this:

https://example.com/wp-json/wp/v2/posts

The parts are:

https://example.com

Your website.

/wp-json/

The REST API root.

wp/v2

The WordPress REST API namespace.

posts

The requested resource.

The API root also exposes information about the routes and namespaces available on the website.

For example:

https://example.com/wp-json/

should normally return JSON describing the available API.

If this URL does not work, there is little point debugging a specific endpoint until the underlying REST API routing problem is understood.

First Test: Open /wp-json/

Before changing anything, test the API directly.

Open:

https://yourdomain.com/wp-json/

Replace yourdomain.com with the actual domain.

If the API is working, you should receive a JSON response.

You can then test a standard endpoint:

https://yourdomain.com/wp-json/wp/v2/posts

If the website has published posts, this should normally return JSON containing them.

This simple test immediately tells you whether the problem affects:

• The entire REST API.
• A specific endpoint.
• Authentication.
• A plugin or custom route.
• A JavaScript request.

If /wp-json/ works but a specific endpoint fails, the problem is likely more specific than the REST API itself.

Common WordPress REST API Errors

The HTTP status code is one of the most useful clues.

Common errors include:

• 400 Bad Request.
• 401 Unauthorized.
• 403 Forbidden.
• 404 Not Found.
• 405 Method Not Allowed.
• 500 Internal Server Error.
• 502 Bad Gateway.
• 503 Service Unavailable.

There can also be WordPress-specific JSON error responses containing a code, message, and data object.

Do not treat every REST API error as the same problem.

The status code and response body can often tell you where to start investigating.

400 Bad Request

A 400 response generally means the request is invalid.

Possible causes include:

• Invalid parameters.
• Incorrect JSON.
• Missing required data.
• Invalid endpoint arguments.
• Incorrect request structure.
• Plugin-generated validation errors.

For example, an application might send a request expecting one format while the WordPress endpoint expects another.

Start by checking the actual request.

Look at:

• URL.
• HTTP method.
• Query parameters.
• Request body.
• Headers.
• Authentication.
• Content type.

If you are working with a custom endpoint, check the endpoint’s registered arguments and validation rules.

WordPress REST API schemas define the expected structure of endpoint data and can be used to validate and sanitize input.

401 Unauthorized

A 401 response usually points toward authentication.

This becomes particularly important when trying to:

• Create posts.
• Update posts.
• Delete content.
• Upload media.
• Access private data.
• Use protected custom endpoints.

WordPress supports several authentication approaches. For logged-in requests within WordPress, cookie authentication and REST API nonces are commonly used. For external applications, Application Passwords are one of the built-in approaches documented by WordPress.

For example, a request might successfully retrieve:

/wp-json/wp/v2/posts

but fail when trying to create a post.

That does not necessarily mean the REST API is broken.

It may simply mean that the request is not authenticated correctly or that the authenticated user does not have the required capability.

Check Authentication Headers

When authentication is involved, inspect the request headers.

A browser request may use:

X-WP-Nonce

For external access using Application Passwords, the request can use HTTP authentication.

WordPress specifically recommends Application Passwords for external REST API authentication rather than using a basic-authentication plugin intended for development and testing.

403 Forbidden

A 403 response means the server or application understood the request but refused to allow it.

This can be caused by:

• Incorrect user permissions.
• REST API permission callbacks.
• Security plugins.
• Web application firewalls.
• Hosting security rules.
• ModSecurity.
• Cloudflare or another proxy.
• Custom authentication code.
• Server rules.

A particularly important distinction is between authentication and authorization.

Authentication answers:

“Who are you?”

Authorization answers:

“Are you allowed to perform this action?”

A user can therefore be successfully authenticated and still receive a 403 because they do not have permission to perform the requested operation.

WordPress REST API endpoints can define a permission_callback to determine who can access them.

404 Not Found

A 404 is one of the most common REST API problems.

For example:

https://example.com/wp-json/wp/v2/posts

might return a 404 instead of JSON.

There are several possible causes.

Check Permalinks

Go to:

WordPress Dashboard → Settings → Permalinks

You do not necessarily need to change the permalink structure.

Simply saving the existing settings can refresh WordPress rewrite rules.

Then test:

/wp-json/

again.

WordPress documents that /wp-json/ relies on the site’s permalink configuration. If pretty permalinks are not enabled, the REST API can instead be accessed through:

/?rest_route=/

This gives you a useful diagnostic test.

Try:

https://example.com/?rest_route=/

If that works while:

https://example.com/wp-json/

does not, rewrite or permalink handling becomes a strong suspect.

Check Whether a Specific Endpoint Exists

The REST API index can tell you which namespaces and routes are available.

Open:

https://example.com/wp-json/

and search the response for:

wp/v2

You can also inspect whether the route you need exists.

For example:

wp/v2/posts

is a standard WordPress endpoint.

If you are working with a plugin or custom post type, its route may be different.

Do not assume that every custom post type automatically exposes the same REST API route.

405 Method Not Allowed

A 405 usually means that the route exists but the HTTP method being used is not supported for that endpoint.

For example, you might send:

POST

to an endpoint that only supports:

GET

WordPress maps HTTP methods to endpoint behavior. A route can therefore exist while only supporting certain operations.

Check:

• The HTTP method.
• The endpoint URL.
• The registered endpoint.
• Authentication.
• Permissions.

If you are developing a custom endpoint, inspect how the route was registered.

500 Internal Server Error

A 500 response usually means something went wrong on the server while processing the request.

Possible causes include:

• PHP fatal errors.
• Plugin conflicts.
• Theme errors.
• Invalid custom code.
• Memory problems.
• Database errors.
• PHP version compatibility.
• Broken REST API callbacks.
• Server configuration problems.

A 500 error is therefore not specifically a “REST API error.”

The REST API may simply be the request that happens to trigger the underlying WordPress or PHP problem.

If the site also produces normal 500 errors outside the API, use your existing guide on How to Fix the WordPress 500 Internal Server Error and investigate the underlying server or PHP error.

Check the WordPress Debug Log

When a REST API request produces a 500 response, the WordPress debug log can be extremely useful.

In a development or controlled troubleshooting environment, you can enable debugging in wp-config.php:

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

This allows errors to be written to:

/wp-content/debug.log

Do not leave detailed debugging output displayed publicly on a production website.

The goal is to capture the underlying error while preventing visitors from seeing PHP warnings or sensitive debugging information.

If the REST request triggers a fatal error, the log can reveal the plugin, theme, file, function, or line that caused it.

Check PHP and Server Logs

The WordPress debug log is not the only source of information.

Your hosting environment may also provide:

• PHP error logs.
• Apache logs.
• Nginx logs.
• ModSecurity logs.
• Firewall logs.
• Access logs.

This becomes particularly important when the request never reaches WordPress.

For example, if a firewall blocks:

POST /wp-json/...

WordPress may have no opportunity to generate its own REST API error.

In that situation, the server or security layer needs to be investigated.

Temporarily Test Plugin Conflicts

Plugins are one of the most common things to investigate when a REST API suddenly stops working.

A plugin can:

• Modify REST API authentication.
• Register custom endpoints.
• Block REST requests.
• Modify API responses.
• Add security restrictions.
• Generate PHP errors.
• Alter HTTP headers.
• Interfere with JavaScript.

If you already have a troubleshooting workflow for plugin and theme conflicts, use it here rather than randomly changing multiple settings at once.

Your existing guide on How to Diagnose and Resolve WordPress Plugin and Theme Conflicts can be used as a deeper troubleshooting reference.

Test With Plugins Disabled

If possible, use a staging environment.

Then:

• Disable plugins.
• Test /wp-json/.
• Test the failing endpoint.
• Re-enable plugins.
• Test again.
• Enable plugins one at a time.

This can help identify the plugin responsible.

If the REST API starts working after disabling a particular plugin, you have a much stronger lead than simply reinstalling WordPress or changing server settings.

Test the Theme

The active theme can also interfere with the REST API.

A theme may contain:

• Custom REST API hooks.
• Authentication filters.
• PHP errors.
• Custom AJAX logic.
• API response modifications.
• Incorrect custom code.

If the problem continues with plugins disabled, temporarily test with a default WordPress theme on staging.

If the REST API starts working, investigate the theme’s custom functionality.

Security Plugins Can Block REST API Requests

Security plugins can deliberately restrict REST API access.

This is sometimes done as a security measure, but it can also break legitimate functionality.

Check whether the website uses:

• REST API restrictions.
• Login protection.
• Firewall rules.
• Bot protection.
• XML/JSON request filtering.
• Rate limiting.
• IP restrictions.
• Custom security rules.

Do not immediately disable every security feature on a live website.

Instead, check the security plugin’s logs and determine whether it is blocking the specific request.

Check Cloudflare and Other Proxies

If the website uses Cloudflare or another reverse proxy, the request may pass through additional security and caching layers before reaching WordPress.

A REST API request can therefore fail because of:

Browser → Cloudflare → Web Server → WordPress → Plugin

rather than because of WordPress itself.

Check:

• Firewall events.
• WAF rules.
• Rate limiting.
• Bot protection.
• Cache behavior.
• Request headers.

If the firewall log shows that the REST API request was blocked, investigate that rule before changing WordPress code.

Check the Browser Developer Tools

When the REST API error appears in the WordPress admin or on the front end, browser developer tools can provide much more information than the visible error message.

Open:

Chrome → Developer Tools → Network

Then reproduce the problem.

Look for a request containing:

/wp-json/

or:

wp-json/wp/v2/

Click the request and inspect:

• Request URL.
• Request method.
• Status code.
• Request headers.
• Response headers.
• Response body.
• Payload.
• Timing.

The response body is particularly useful.

Instead of simply seeing:

403

you may see a WordPress JSON error explaining why the request was rejected.

WordPress REST API responses are designed to communicate data and errors through JSON, which makes the response body an important part of debugging.

Check the JavaScript Console

If a frontend feature depends on the REST API, also open:

Developer Tools → Console

Look for errors such as:

Failed to fetch

401 Unauthorized

403 Forbidden

Unexpected token '<'

That last example can be particularly useful.

If JavaScript expects JSON but receives HTML instead, the request may have been redirected to:

• A login page.
• A 404 page.
• A security challenge.
• A server error page.

For example, the browser may expect:

{
  "id": 123,
  "title": "Example"
}

but instead receive:

<html>
...

That usually indicates that something other than the expected REST API response was returned.

Check the Response Content Type

A normal REST API response should generally be JSON.

If your endpoint returns:

text/html

instead of JSON, investigate why.

Possible causes include:

• PHP warnings.
• A server error page.
• A redirect.
• A security challenge.
• A maintenance page.
• A plugin injecting output.
• Incorrect server configuration.

This is a useful clue because the problem may not actually be the REST endpoint itself.

Test the API With cURL

Testing outside the browser is another good way to isolate the problem.

For example:

curl -i https://example.com/wp-json/

You can test a specific endpoint:

curl -i https://example.com/wp-json/wp/v2/posts

The -i option shows the HTTP response headers as well as the response body.

This helps you inspect:

• HTTP status.
• Content type.
• Redirects.
• Server headers.
• REST API response.

If the browser fails but cURL works, investigate browser-side JavaScript, authentication, CORS-related behavior, or the application making the request.

If both fail, the problem is more likely to be server-side or WordPress-side.

Test With a REST API Client

For more advanced troubleshooting, tools such as Postman can make it easier to control:

• HTTP method.
• URL.
• Headers.
• Authentication.
• Request body.

This is useful when debugging custom integrations.

You can compare:

Working request

against:

Failing request

and identify what changed.

The WordPress REST API is designed to work over HTTP and can be accessed by applications running in browsers, PHP, Python, Java, and other environments.

Authentication Problems With Nonces

If you are developing a JavaScript-based WordPress feature, authentication can involve a REST API nonce.

WordPress uses the wp_rest nonce action for REST API requests made through cookie authentication. The nonce can be sent through the _wpnonce parameter or the X-WP-Nonce header.

For example:

X-WP-Nonce: abc123...

If the nonce is missing, expired, or generated incorrectly, an authenticated request may fail.

This is particularly relevant when:

• Custom JavaScript calls the API.
• A plugin creates its own admin interface.
• A frontend application communicates with WordPress.
• AJAX functionality has been customized.

Do not assume that a successful WordPress login automatically means every REST API request is authenticated correctly.

Application Password Problems

For external applications that need to authenticate with WordPress, Application Passwords can be useful.

For example, an external service may need to create posts through:

/wp-json/wp/v2/posts

The request must be authenticated with a WordPress user that has the appropriate permissions.

If authentication fails, verify:

• Username.
• Application Password.
• HTTPS.
• Request headers.
• User capabilities.
• Security/firewall rules.

WordPress’s official documentation recommends Application Passwords for external REST API authentication and specifically warns against using basic-authentication plugins as a production authentication solution.

Check Whether REST API Has Been Disabled

Some security configurations attempt to disable or restrict the WordPress REST API.

This can create unexpected problems.

WordPress itself advises against simply disabling the REST API because parts of WordPress administration depend on it. Instead, access can be restricted through authentication where appropriate.

Search your website for code or settings that modify:

rest_authentication_errors

or other REST-related filters.

Also check security plugins for REST API restrictions.

If a plugin or custom snippet is blocking anonymous REST requests, determine whether the request actually needs to be public before changing the restriction.

Check Custom REST API Endpoints

If the failing endpoint is not a standard WordPress endpoint, investigate how it was registered.

A custom route normally uses:

register_rest_route()

and can define:

• Namespace.
• Route.
• HTTP methods.
• Callback.
• Permission callback.
• Arguments.

For example, a custom endpoint might look conceptually like:

/wp-json/my-plugin/v1/products

If that endpoint returns an error, inspect the callback and permission callback.

WordPress documents that REST API endpoints can use callbacks to process requests and permission callbacks to control access.

Check the Permission Callback

A custom endpoint can work perfectly for an administrator but fail for another user.

For example:

Administrator → 200 OK

Editor → 403 Forbidden

Logged-out visitor → 401/403

That may be intentional.

Check the endpoint’s permission logic before assuming the API is broken.

This is particularly important for custom plugins and membership systems.

Check Query Parameters

Some REST API errors are caused by invalid parameters rather than the endpoint itself.

For example:

/wp-json/wp/v2/posts?per_page=100

may behave differently from:

/wp-json/wp/v2/posts?per_page=10

WordPress REST API endpoints support numerous parameters for filtering, pagination, searching, embedding, and other operations. The API documentation provides endpoint-specific parameters and schemas.

If an API request fails, remove optional parameters and test the simplest version first.

For example:

/wp-json/wp/v2/posts

If that works, add parameters one at a time.

This is much faster than debugging a large request with ten variables at once.

Check Pagination

Large API requests can create additional problems.

Instead of requesting an extremely large amount of data at once, use pagination.

For example:

/wp-json/wp/v2/posts?per_page=10&page=1

Then:

/wp-json/wp/v2/posts?per_page=10&page=2

This reduces the amount of data returned in each request and makes troubleshooting easier.

WordPress provides pagination parameters across many REST API collections.

Check PHP Memory and Resource Limits

A REST API request is still a WordPress request.

That means it can be affected by:

• PHP memory.
• PHP execution time.
• CPU resources.
• Database performance.
• PHP workers.

If a large API request causes a 500 error or timeout, resource limits can become relevant.

If you encounter memory-related errors, use the existing WordPress Memory Limit Errors guide to investigate PHP and WordPress memory limits.

Do not simply increase memory without finding out why the request needs so much.

A custom endpoint that loads thousands of database records may have a query or pagination problem rather than simply needing more memory.

Check Database Errors

A REST API endpoint may depend on database queries.

For example, a custom endpoint could:

• Receive a request.
• Query hundreds of posts.
• Load metadata.
• Run additional queries.
• Build a large JSON response.

If one of those operations fails, the REST API may return a server error.

If database problems are suspected, inspect the server/PHP logs and use a tool such as Query Monitor in a controlled environment.

Avoid making database changes on a live website without a current backup.

Check WordPress Updates and Plugin Compatibility

If the REST API worked previously and suddenly stopped after an update, identify what changed.

Possible changes include:

• WordPress core update.
• Plugin update.
• Theme update.
• PHP update.
• Hosting configuration change.
• Security plugin update.
• CDN/WAF rule change.

Do not immediately roll everything back.

First identify which component changed and reproduce the problem on staging if possible.

Your existing staging environment guide is useful here because API problems are much safer to investigate away from the live website.

REST API Errors in Elementor and Page Builders

Page builders and frontend plugins can also rely on REST API requests.

If an Elementor or other page-builder feature suddenly stops working, inspect the browser’s Network tab rather than assuming the page builder itself is broken.

Look for:

/wp-json/

requests and inspect their status codes.

For example:

200 usually means the request completed successfully.

401/403 points toward authentication or permissions.

404 points toward routing or endpoint problems.

500 points toward a server-side or PHP problem.

This approach gives you a concrete starting point instead of randomly disabling plugins.

A Reliable REST API Debugging Workflow

When you encounter a REST API error, follow the same sequence every time.

Step 1: Identify the Exact Request

Find the failing request in browser Developer Tools.

Write down:

• URL.
• Method.
• Status code.
• Response.
• Request payload.

Step 2: Test /wp-json/

Open:

/wp-json/

If it fails, investigate the global API/routing problem.

If it works, continue.

Step 3: Test the Specific Endpoint

For example:

/wp-json/wp/v2/posts

Determine whether the problem affects the entire API or only one route.

Step 4: Remove Optional Parameters

Test the simplest possible request.

Then add parameters one at a time.

Step 5: Check Authentication

If the request is protected, verify:

• Login state.
• Nonce.
• Application Password.
• Authorization header.
• User capabilities.

Step 6: Check Plugins and Security

Look for:

• Security plugins.
• Firewalls.
• REST API restrictions.
• Recent plugin changes.

Step 7: Check Logs

Inspect:

• WordPress debug log.
• PHP logs.
• Server logs.
• Firewall logs.

Step 8: Test on Staging

If possible, reproduce the problem on staging and disable plugins or switch themes one at a time.

Step 9: Test Outside the Browser

Use cURL or another API client.

This helps determine whether the issue is in WordPress, the browser, or the application making the request.

Step 10: Fix the Root Cause

Do not stop at making the error disappear.

Find out why the request failed and make sure the fix does not break other REST API functionality.

Quick REST API Troubleshooting Table

Error	Common causes	What to check first
400	Invalid request or parameters	URL, method, payload, parameters
401	Authentication problem	Login, nonce, Application Passwords
403	Permission/security restriction	User capabilities, security plugin, firewall
404	Route or rewrite problem	Permalinks, endpoint URL, route
405	Unsupported HTTP method	GET/POST/PUT/DELETE
500	PHP/plugin/server error	Debug log, PHP logs, plugin conflicts
502	Gateway/server communication	Hosting, proxy, PHP-FPM
503	Service unavailable	Server resources, maintenance, hosting

The status code is only the starting point. Always inspect the response body and server-side logs when available.

How to Prevent REST API Problems

You cannot prevent every API error, but you can make your WordPress installation easier to troubleshoot.

Keep WordPress, plugins, themes, and PHP versions maintained.

Use staging before major changes.

Avoid unnecessary code that globally blocks REST API requests.

Use proper authentication for protected endpoints.

Validate and sanitize data in custom endpoints.

Use permission callbacks for protected resources.

Keep API requests reasonably small.

Use pagination for large datasets.

Monitor server and PHP errors.

Keep security rules specific rather than blocking the entire API without understanding what depends on it.

And when you add custom REST API functionality, document the endpoint, expected parameters, authentication requirements, and possible responses.

Final Thoughts

WordPress REST API errors can look complicated because several different systems can be involved in a single request.

A request may pass through:

Browser → CDN/WAF → Web Server → WordPress → Plugin/Theme → Database

An error at any stage can appear as a REST API problem.

The most effective approach is therefore not to start changing random WordPress settings.

Start with the actual request.

Find the endpoint.

Check the HTTP method.

Read the status code.

Inspect the JSON response.

Check authentication.

Then move down the stack through plugins, security systems, PHP, the database, and the server.

Once you know where the request fails, the solution is usually much easier to identify.

The WordPress REST API is a core part of modern WordPress and is designed to expose structured resources through predictable routes and HTTP requests. Understanding how those requests work gives you a much better way to diagnose problems with plugins, JavaScript applications, integrations, and custom WordPress functionality.

For more practical WordPress development, performance, security, SEO, and WooCommerce guidance, you can also explore the WP Flow Mastery WordPress eBook.

Written by Nemanja Stosic

WordPress Developer & Website Optimization Specialist

Nemanja has worked on more than 200 websites and focuses on WordPress development, performance optimization, SEO, security, WooCommerce, and practical website improvements.