How to Fix 404 and 403 Errors from Your Site's REST API

What 404 and 403 mean in an API

In a REST API the status code is the first thing a client reads, so it pays to know exactly what each one claims:

The important question is who sent the response. A 404 or 403 can come from your application code, from the web server before the application ever runs, from a CDN or firewall in front of the server, or from a security plugin inside the application. Each layer leaves different fingerprints in the body and headers, and each needs a different fix. A generic HTML error page from nginx and a JSON error object from your API framework both carry a 404, but they point to completely different problems.

Some APIs deliberately answer 404 instead of 403 when a caller is not allowed to see a record, so as not to reveal that it exists. If your own API does that, a 404 for an existing record may really be a permission problem.

The common causes, layer by layer

Work from the outside in. If the request never reaches your application, no amount of changing application code will help, and the same goes in reverse. The 403 errors guide and the 404 errors guide cover these codes for normal web pages, which share many of the server-level causes.

How to reproduce the error with curl and Postman

Start with curl, because it sends exactly what you type and shows every header in the response:

curl -i -X GET https://www.example.com/wp-json/wp/v2/posts?per_page=1

The -i flag prints the status line and headers above the body. Read three things:

• The body. A JSON error with a code field came from the application. A plain HTML page came from the web server, CDN or firewall.
• The Server header. cloudflare with a block page means the CDN answered. nginx or Apache with an HTML page means the web server did.
• Any request ID header, such as cf-ray. Use it to find the event in your CDN or firewall logs.

To send credentials with curl, use -u for a username and password, or --oauth2-bearer for a bearer token:

curl -i -u "editor:abcd efgh ijkl mnop qrst uvwx" \
  -X POST https://www.example.com/wp-json/wp/v2/posts \
  -H "Content-Type: application/json" \
  -d '{"title":"Test","status":"draft"}'

curl -i --oauth2-bearer "$API_TOKEN" https://api.example.com/v1/orders/1042

404 error in Postman

When Postman shows a 404, check the request it really sent, not the one you think it sent. Open the Postman Console from the bottom bar and look at the full address. Common faults are an environment variable such as {{baseUrl}} that is empty or points at staging, a missing /wp-json or /api/v1 prefix, a double slash where two variables join, and the wrong method in the dropdown.

403 Forbidden error in Postman

For a 403, check the request's auth settings tab. A request set to inherit from its collection sends nothing if the collection has no auth set. Check the type matches what the API expects, and that the token has not expired. If curl succeeds with the same credentials and Postman fails, compare headers in the console. Some firewalls block the default Postman user agent string.

WordPress REST API 404 and 403 errors

The WordPress REST API lives under /wp-json/. A request to https://www.example.com/wp-json/ should return a JSON index of the available routes. If it returns an HTML 404 page, WordPress never saw the request.

wp-json returns 404

• Plain permalinks or missing rewrites. Go to Settings, then Permalinks, and click Save Changes without changing anything. That regenerates the rewrite rules. On Apache, check .htaccess still holds the standard WordPress block.
• nginx without a WordPress location rule. The main location must pass unknown paths to WordPress:

location / {
    try_files $uri $uri/ /index.php?$args;
}

A quick test that bypasses pretty permalinks is the query form of the route. If this works while /wp-json/ fails, the problem is rewriting, not the API:

curl -i "https://www.example.com/?rest_route=/wp/v2/posts&per_page=1"

A JSON response with the code rest_no_route means WordPress received the request but no route matches the path and method. Check the namespace and version in the path, the HTTP method, and that the plugin registering a custom route is active.

WordPress REST API returns 403 or 401

• Not logged in. Requests that create or edit content need credentials. WordPress usually answers 401 when no user is identified and 403 when the user lacks the capability.
• Cookie requests without a nonce. JavaScript on your own site using the login cookie must also send a REST nonce in the X-WP-Nonce header. Without it WordPress treats the request as logged out and returns a 401; an invalid nonce gives rest_cookie_invalid_nonce.
• Application Passwords not reaching PHP. On some Apache set-ups with PHP running as CGI or FastCGI, the credentials header is stripped before PHP sees it. On Apache 2.4.13 or later, add CGIPassAuth On to the site's .htaccess or virtual host.
• Security plugins. Many security plugins can restrict the REST API to logged-in users, or block routes such as /wp/v2/users. Check their settings before changing server rules.

See the WordPress HTTP errors guide for other status codes from the same site.

Firewall, server and framework causes

Web application firewalls

A WAF inspects each request and can block API calls whose JSON body contains strings that look like SQL or script injection, or whose user agent looks automated. The block usually comes back as a 403 HTML page. On Cloudflare, open Security, then Events, and search by the cf-ray value from the response to see which rule fired. On Plesk with ModSecurity, check the web application firewall log and the domain error log for the rule ID. Then write a narrow exception for that rule on your API path, rather than switching the firewall off. The Plesk HTTP errors guide shows where those settings live.

Web server rules

Check the access and error logs for the exact request:

sudo grep ' /api/v1/orders' /var/log/nginx/access.log | tail -5
sudo tail -20 /var/log/nginx/error.log

An entry in the access log with 403 and an error log line mentioning access forbidden by rule means an nginx deny rule matched. A 404 in the access log with no matching application log means the location block did not hand the request to the application.

Application frameworks

In Node.js with Express, a route that exists only for GET answers a POST with a 404 and a body such as Cannot POST /api/v1/orders. The same body appears when a router is mounted at a different prefix from the one the client uses. List your registered routes and compare them with the request. The Node.js HTTP errors guide covers error handling in more depth.

A worked example

Example Bakery's order form posted to /wp-json/bakery/v1/orders. It worked in Postman, but the live form failed. The browser's Network panel showed a 403 with an HTML body and a Server: cloudflare header, so the application was never reached.

Searching Cloudflare Security Events by the cf-ray ID showed a managed WAF rule matching the order notes field, which contained an apostrophe followed by the word or. The fix was a WAF exception that skipped that one rule for that one path. The next request returned a 401 instead, this time as JSON from WordPress, because the form's JavaScript was not sending the X-WP-Nonce header. Adding the nonce brought a 201 Created.

Two layers, two different fixes. Reading the body and headers first saved hours of changing code in the wrong place.

The fix, step by step

Edge cases worth knowing

• Preflight requests. Browsers send an OPTIONS request before many cross-origin calls. If your server or firewall answers it with 403 or 404, the real request is never sent. Allow OPTIONS on API routes.
• Cached errors. A CDN can cache a 404 or 403 from an earlier broken deployment. Send Cache-Control: no-store on API responses that should not be cached, and purge after fixing.
• Redirects that change the method. An http to https or trailing slash redirect can turn a POST into a GET, which then hits a GET-only route and returns 404. Call the final address directly.
• Bot rules. Rules written to block scrapers or AI crawlers can catch your own integrations. Check the AI crawler access guide if you have such rules.
• Rate limits. The correct code is 429, but some firewalls use 403. A 403 that appears only after many fast calls is probably a rate limit.

Keeping the API reliable

1. Add a health route such as /api/v1/health that returns 200, and monitor it from outside your network so you hear about rewrite and firewall problems first.
2. Return JSON errors with clear codes from the application, so any HTML error page is instantly recognisable as coming from another layer.
3. Keep a saved Postman collection with one working request per route and method, and run it after server, plugin or firewall changes.
4. Log request IDs in the application and pass them back in a response header, so you can match a failed call to a log line in seconds.
5. Review firewall exceptions every few months and keep them as narrow as possible: one rule, one path.