Understanding 404 and 401 REST API Errors in WordPress
When a custom plugin starts returning REST API errors, two of the most common responses are 404 Not Found and 401 Unauthorized. Although they can look similar at first glance, they usually point to very different problems.
A 404 error often means the endpoint route was never registered correctly, the URL is wrong, or something on the server is blocking the request before WordPress can handle it. A 401 error usually means the route exists, but the request is not authenticated or does not have permission to access the resource.
If you build custom WordPress plugins that expose REST endpoints, understanding the difference between these errors can save a lot of debugging time. The goal is to determine whether the issue is in route registration, permissions, authentication, or the server configuration.
Fixing WordPress REST API 404 Errors in Custom Plugins
A 404 response from a custom REST endpoint usually means WordPress never matched the request to a valid route. In many cases, the plugin code is fine in principle, but one small detail prevents the endpoint from being recognized.
1. Confirm the route is registered on the correct hook
Custom REST routes should be registered on the rest_api_init action. If you register routes too early, WordPress may not know about them when the API loads.
Example pattern:
add_action(‘rest_api_init’, function () { register_rest_route(‘my-plugin/v1’, ‘/items’, array(…)); });
If your route registration is outside of rest_api_init, move it there and test again.
2. Check the namespace and route path carefully
REST API URLs are sensitive to the namespace and path you define. A typo in the namespace, version, or endpoint slug can produce a 404 even if the rest of your plugin works perfectly.
Compare the registered route with the request URL. For example, if you register my-plugin/v1/items, the request must match that structure exactly.
- Verify spelling in the namespace
- Check singular vs plural route names
- Make sure the version number matches
- Confirm there are no extra or missing slashes
3. Make sure pretty permalinks and rewrite rules are working
Sometimes the REST API appears broken because the site’s rewrite rules are stale or the server is not handling permalinks correctly. This is especially common on local development environments or after migrations.
Try visiting the site’s permalink settings and saving them again to flush rewrite rules. Also confirm that the REST API base URL, usually /wp-json/, is reachable.
If the entire REST API is returning 404s, the issue may be broader than your plugin.
4. Test the endpoint directly
Before assuming your plugin code is wrong, test the endpoint in a browser or with a tool like curl or Postman. If the route is not listed in the REST index, WordPress has not registered it correctly.
You can also inspect the REST API index at /wp-json/ to see whether your namespace appears. If it does not, the problem is likely in route registration or plugin loading order.
5. Watch for plugin loading conflicts
Another plugin or a custom theme may interfere with REST requests. Security plugins, caching layers, and endpoint filters can all block routes or alter responses.
- Temporarily disable other plugins
- Switch to a default theme for testing
- Check for filters such as rest_authentication_errors
- Review any security or firewall settings
6. Check for server-level blocking
In some cases, the request never reaches WordPress. Web server rules, proxy settings, or security modules may block the request path before the REST API can respond.
If a custom endpoint works in one environment but not another, compare server configuration, .htaccess rules, nginx location blocks, and any WAF or CDN settings.
Fixing WordPress REST API 401 Errors in Custom Plugins
A 401 error means WordPress recognized the endpoint but rejected the request because authentication or authorization failed. In custom plugins, this often comes down to the callback permissions or the way the request is authenticated.
1. Review the permission_callback
Every custom REST route should define a permission_callback. This function determines whether the current user or request is allowed to access the endpoint.
If your callback returns false, WordPress will deny access. If it is too strict, valid users may receive 401 or 403-style failures depending on the context.
Use a permission callback that matches the endpoint’s purpose. Public data may return __return_true, while sensitive actions should check capabilities such as current_user_can().
2. Confirm the request is authenticated correctly
If your endpoint requires a logged-in user, make sure the request includes valid authentication. Common methods include cookie authentication for browser sessions, application passwords, or nonce-based requests from the admin area.
- For browser-based requests, verify the user is actually logged in
- For JavaScript requests, include a valid REST nonce
- For external clients, use application passwords or another supported auth method
- Check whether the auth headers are being stripped by a proxy or server
3. Validate user capabilities
Sometimes authentication succeeds, but authorization fails because the user lacks the required capability. For example, a subscriber should not be able to access an endpoint that updates plugin settings.
Use capability checks that match the action being performed. For example, an endpoint that edits site content may require edit_posts or a more specific custom capability.
If your endpoint is intended for administrators only, make that requirement explicit in the permission callback.
4. Check nonce handling in JavaScript requests
Many custom plugins use JavaScript to call REST endpoints. In that case, a missing or invalid nonce can lead to unauthorized responses.
Make sure the nonce is generated correctly in PHP and passed to your script. Then confirm it is included in the request headers as expected.
Also remember that nonces expire. If a site stays open in a browser tab for a long time, a previously valid nonce may no longer work.
5. Inspect authentication and security plugins
Security plugins, SSO tools, and login protection layers can change how REST API requests are authenticated. They may block unauthenticated requests, require special headers, or invalidate cookie-based access.
If you see 401 errors only on production, review the security stack carefully. Compare behavior with staging and confirm whether any plugin is filtering REST requests or blocking specific routes.
6. Use logging to pinpoint the failure
When the cause is unclear, add temporary logging inside your route callback and permission callback. This helps you determine whether the request reaches the code at all and what the permission logic returns.
Useful checks include:
- Whether the callback is triggered
- What user ID is detected
- Whether the permission callback returns true or false
- Whether authentication headers are present
Logging often reveals whether you are dealing with a route problem, a permission problem, or an auth problem.
Best Practices to Prevent REST API Errors in Custom Plugins
The easiest REST API errors to fix are the ones you prevent early. A few development habits can reduce 404 and 401 issues dramatically.
- Register routes on rest_api_init
- Use consistent namespaces and versioning
- Always include a clear permission_callback
- Test endpoints with both logged-in and logged-out users
- Verify behavior across local, staging, and production environments
- Document required authentication methods for each endpoint
It also helps to keep endpoints small and focused. A route that does one thing well is easier to secure and debug than a route that tries to handle too many scenarios.
Quick troubleshooting checklist
If your custom plugin REST API is returning 404 or 401 errors, run through this checklist:
- Is the route registered on rest_api_init?
- Does the request URL exactly match the namespace and route?
- Is the REST API index showing your endpoint?
- Are permalinks and rewrite rules working?
- Does the permission callback allow the current user?
- Is the request authenticated with the right method?
- Are security or caching plugins interfering?
- Is the server or proxy blocking the request?
Following this sequence usually reveals the issue quickly and keeps debugging focused.
Conclusion
WordPress REST API 404 and 401 errors in custom plugins are common, but they are usually straightforward once you know where to look. A 404 points to route registration, URL mismatch, rewrite rules, or server-level blocking. A 401 points to authentication, permissions, nonce handling, or capability checks.
By testing the endpoint directly, reviewing your permission_callback, and confirming the route is registered correctly, you can solve most REST API issues without guesswork. If you build custom plugins regularly, keeping these checks in your development workflow will make your endpoints more reliable and easier to maintain.
For more details on the WordPress REST API, see the official documentation at developer.wordpress.org/rest-api/.