WordPress REST API Custom Endpoint Returns 404 – register_rest_route Fix Guide
🚧 Why Your Custom REST API Endpoint Returns 404
You’ve registered a custom endpoint using register_rest_route(), but when you try to access it,
WordPress returns a 404 Not Found error. This is a common frustration for WordPress developers.
The issue usually lies in the registration hook, permalink structure, or the request method.
🔍 Common Causes of 404 on Custom Endpoints
- register_rest_route called too early or too late – Must be hooked to
rest_api_init. - Permalinks not flushed – WordPress needs to rebuild rewrite rules after adding new routes.
- Missing namespace or route path – The endpoint URL does not match the registered route.
- HTTP method mismatch – Using POST when the route only accepts GET (or vice versa).
- Authentication or permission callback – If the permission callback returns false, the endpoint may appear as 404.
- Plugin/theme conflict – Another plugin overrides the route or disables the REST API.
- Server configuration – ModSecurity or custom rewrite rules may block the request.
📝 Proper Usage of register_rest_route
The function must be hooked to rest_api_init. Here’s a minimal working example:
The endpoint will be available at:
https://yoursite.com/wp-json/myplugin/v1/test/
register_rest_route directly in the root of the file without the rest_api_init hook.
This will cause the route to be registered too early and be ignored.
🔄 Flush Permalinks (Rewrite Rules)
After registering a new route, you must flush rewrite rules so WordPress knows about the new endpoint. You can do this by:
- Going to Settings → Permalinks and clicking Save Changes (even without changes).
- Programmatically:
flush_rewrite_rules();(but avoid calling it on every page load — use it once during plugin activation).
If you’re testing on a local environment, simply visiting the Permalinks page is the quickest fix.
🔎 Debugging Steps
1. Check if REST API is enabled
Visit /wp-json/ on your site. If you see a JSON response with routes, the REST API is working.
If you get a 404, your permalinks may be set to plain (e.g., ?p=123). Switch to a pretty permalink structure.
2. Verify the route is registered
Use the rest_get_server() to list all registered routes:
If the route is not in the list, your registration didn’t work — check the hook and namespace.
3. Enable WP_DEBUG
Add define('WP_DEBUG', true); to wp-config.php to see any PHP errors that might
prevent the route from being registered.
4. Check the permission callback
If you have a permission callback that returns false, the endpoint may return a 404 or 403.
Ensure your callback returns true or WP_Error for proper handling.
📬 Testing with Postman / cURL
Use tools like Postman or cURL to test your endpoint:
If you get a 404, double‑check the URL structure. If you get a 200 with the expected data, your endpoint works.
✅ Best Practices for Custom REST Endpoints
- Always use the
rest_api_inithook to register routes. - Flush rewrite rules after adding new routes (preferably on plugin activation).
- Use a unique namespace (e.g.,
myplugin/v1) to avoid conflicts. - Provide a permission callback to secure your endpoints.
- Validate and sanitize input using
sanitize_text_fieldandrest_ensure_request. - Return a
WP_REST_Responsewith proper status codes. - Test thoroughly with different HTTP methods and parameters.
- Keep your plugin/theme updated to avoid compatibility issues.
Explore More Free Learning Resources
© 2026 FreeLearning365.com •
Built with for learners worldwide.
All rights reserved. Content may not be reproduced without permission.
No comments:
Post a Comment
Thanks for your valuable comment...........
Md. Mominul Islam