404 Not Found In API | Stop Missing Endpoints

A 404 Not Found In API response means your request reached a server, but the exact path you asked for doesn’t exist there.

You send a request you’re sure should work, then a tidy 404 comes back. No crash. No timeout. Just a dead end. It’s maddening because it feels like you did everything right.

The good news is that a 404 is rarely random. It usually points to a mismatch between what your client sent and what the server is set up to accept. Find that mismatch and the fix is often small.

This article gives you a repeatable flow that starts with fast, no-drama checks, then moves into routing, proxies, gateways, and deployments. You’ll end with a compact checklist and a table you can keep nearby when the next 404 hits.

What A 404 Means In Api Work

In HTTP, a 404 status says the server can’t find a resource at the URL path you requested. In API work, that “resource” is usually a route like /v1/users, not a web page. Your request can still be well-formed and still get a 404 if the route doesn’t match.

There are two broad sources of API 404s. One comes from a layer in front of your app, like a reverse proxy, gateway, or CDN. The other comes from your app’s own router when it doesn’t have a matching handler.

Read Response Headers — Look at server, via, and any vendor headers to spot the layer that replied.
Compare Error Shape — A plain HTML 404 page often points to a web server layer; a consistent JSON error often points to app routing.
Capture The Full URL — Copy the exact URL string from logs so you don’t “fix” the wrong thing.

One more nuance matters. Some teams return 404 on purpose when auth fails, so outsiders can’t map private routes. If you only see 404 on secured routes, treat auth and tenant routing as suspects, not afterthoughts.

Fast Checks That Catch Most 404s

Most 404s come from small mismatches that hide in plain sight. Do these checks in order. Each one is quick, and each one can save you from chasing the wrong layer.

Confirm You’re Calling The Right Host

It’s easy to point at the wrong base URL after a config swap, a stale mobile build, or a copied snippet that used a sandbox domain. Two hosts can share the same TLS cert and still route to different services.

Log Base URL At Runtime — Print the base URL right before each request, then compare it to what you expect.
Check DNS Resolution — Use dig or nslookup to confirm the domain points to the service you think it does.
Verify Scheme And Port — A different port or http vs https can land you on a different routing stack.

Validate Path, Case, And Slashes

Routes can be strict about casing and trailing slashes. Some routers treat /users and /users/ as different paths. Some treat /Users as a miss.

Copy Path Exactly — Paste the endpoint from the API docs, then compare it to what your client actually sends.
Watch Double Slashes — Joining baseUrl and /path can produce //, which some layers won’t normalize.
Confirm URL Encoding — A space or slash inside an ID can change the path you think you’re requesting.

Make Sure The HTTP Method Matches

Some stacks return 404 when the path exists but the method does not match. You might expect 405. You still get 404, often as a deliberate choice.

Send The Documented Verb — If the endpoint is POST, don’t test with GET and assume the route is missing.
Check Client Defaults — Some SDK calls default to GET unless you set a body or an explicit method.
Inspect Route Listing In Dev — Print the route table locally to confirm method plus path pairing.

Reproduce With Curl To Remove Client Magic

Many clients rewrite URLs, follow redirects, or inject default headers. A direct curl request strips that away and shows what the server does with a plain call.

Send A Minimal Request — Use curl -i with the full URL and only required headers.
Block Redirect Following — A redirect can push you to a different host that returns 404.
Save The Raw Output — Store headers and body in a file so you can compare across attempts.

Fixing 404 Not Found In API Requests

Once you’ve confirmed the host, path, and method, treat the request as a chain. A break at any link can yield a 404. Work from the outside in: public URL, gateway rules, app router, then handler code.

Start With One Known-Good Endpoint

If your service has a health route, version route, or OpenAPI route, test that first. If a known route returns 200, your base URL is likely correct and you can zoom in on why one route misses.

Call A Health Or Status Route — Try /health or /status if your service exposes one.
Check Version Prefix — Confirm whether the API expects /v1, /api/v1, or no prefix.
Match Accept Header — Some routers route by Accept and can send you to a web handler instead of an API handler.

Verify Router Mount Paths

In many codebases, routes are mounted under a parent path. A handler might be defined as /users, yet the router is mounted at /api, making the real route /api/users. A reverse proxy can also add a prefix, which shifts every route in one shot.

Check Where Routers Attach — Find the mount path in your app setup and confirm it matches the public URL.
Compare Local And Deployed Config — A single base-path setting can change the route surface.
Search For Path Rewrites — Look for rules that strip /api or add it, then verify the final upstream path.

Confirm Versioning And Deprecation Rules

APIs that run multiple versions often route by path segment, host, or header. If your request misses the expected version marker, it can fall through to a default router and return 404.

Send Required Version Header — If versioning is header-based, set it on every call through your client wrapper.
Verify Active Version — If /v2 is live, some /v1 paths may be removed or moved.
Check Doc Source — Make sure you’re reading docs for the same service version you’re calling.

Watch For Auth And Tenant Routing That Hides Routes

Some services return 404 instead of 401 or 403 when the token is missing, scoped wrong, or tied to a different tenant. That can make a security issue look like a routing issue.

Test With A Known Working Token — Use a token that succeeds on another endpoint on the same host and version.
Verify Audience And Issuer — A JWT can validate and still fail routing rules if claims don’t match expected values.
Double-Check Tenant Id In Path — If the URL includes an org ID, make sure it matches the token’s tenant.

If you want a quick sanity anchor while debugging, say the phrase to yourself once: “I’m seeing 404 not found in api because the server didn’t match this request to a route.” That keeps you from chasing database bugs and app logic before routing is proven.

404 Errors In Your Api Calls With Proxies And Gateways

When the 404 comes from a layer in front of your app, fixes live in rewrite rules, base path mappings, or routing tables in the gateway. Your job is to identify which layer answered, then adjust only that layer.

Reverse Proxy Prefix And Rewrite Problems

With Nginx or Apache in front, the public path often maps to an internal service path. A tiny config detail can change what the app receives. That makes the app look “broken” when the proxy is quietly reshaping the URL.

Log Incoming And Upstream URIs — Record both the original request URI and the forwarded upstream URI.
Test Proxy Then App Directly — Call the app on its internal address when possible to see if routing works there.
Review Rule Ordering — A broad match can catch traffic meant for your API path and send it elsewhere.

API Gateway Base Path Mappings

Gateways map public URLs to services and stages. A mapping can point to the wrong stage, wrong service, or wrong route set. The backend can be healthy and still look “missing” to callers.

Confirm Active Stage — Verify the stage that receives traffic matches the stage you last deployed.
Validate Route Patterns — A pattern like /users/{id} can miss if the match rules are too strict.
Check Integration Target — Confirm the gateway forwards to the intended upstream host and path.

CDN Caching Of 404 Responses

Some CDNs cache error responses. If a route was missing during a deploy, the edge can keep serving the cached 404 after the route exists. It looks like a code issue until you bypass cache and the route “magically” works.

Purge Cache For The Path — Clear cached entries for the specific endpoint path you’re testing.
Bypass Cache Once — Use cache-bypass headers if your CDN honors them, then compare results.
Set No-Store On Errors — Keep error responses from being cached on API paths unless you intend it.

Platform Traps That Produce Clean 404s

Some platforms produce consistent, well-formed 404s that feel like your app responded. In reality, the platform might not be routing to your code at all. These traps are common in serverless, containers, and monorepos.

Serverless Function Routing Misses

In serverless, a route can exist in source code and still not be reachable if the function name, handler path, or export signature doesn’t match what the platform expects. You call the URL, the platform can’t find the handler, and it returns 404.

Check Deploy Logs — Confirm the function was created and the route was attached during deploy.
Verify Handler Entry Point — Make sure the configured handler matches the file and export name.
Test The Provider URL — Call the direct provider URL, not only the custom domain.

Container Port And Ingress Mismatch

A container can be running while your API process listens on a different port than the service forwards to. A health check can pass on one port while requests route to another, which can surface as 404 depending on what is listening there.

Log Listening Port On Startup — Print the port the app binds to and compare it to service config.
Port-Forward And Call Internally — If you can, call the service inside the cluster to confirm routes.
Review Ingress Path Rules — A one-character path mismatch in ingress config can send traffic to a different service.

Catch-All Routes Swallowing Real Routes

A wildcard handler like /* can swallow more than you expect. Route order matters in many routers. Put the wildcard too early and it blocks the specific routes that come later.

Find Wildcard Handlers — Make sure catch-all routes sit after specific route declarations.
Print Registered Routes — Dump the route list at runtime to verify the router loaded what you think it loaded.
Check Middleware Early Returns — A middleware that ends the response can prevent later routing from running.

Keeping Routes Stable After The Fix

Once you fix the immediate miss, add small guardrails so a later refactor doesn’t bring the same pain back. You want missing routes to show up in your build pipeline, not in user reports.

Add Contract Checks For Each Route Group

A contract check can be as simple as one call that asserts “this route exists and returns the expected status.” You don’t need to test every edge case here. You do want a fast signal that a route group still exists.

Call One Happy Path — Use a stable test record and assert 200 or 204 for core routes.
Assert Error Format — When a record is missing, assert your chosen JSON error shape stays consistent.
Run In CI — Fail the build if the route surface changes without intention.

Log What The Edge Forwards

If a gateway or proxy rewrites paths, record the incoming path and the forwarded path. When a 404 appears, you can see whether rewriting changed the request in a way that broke routing.

Record Original URL — Store the raw path and query string in request logs.
Record Upstream URL — Store what was forwarded to the backend after rewrites.
Tag Logs With Build Id — Link spikes in 404 responses to a specific deploy.

Quick Reference Table

What You See	Most Likely Cause	Fast Check
Generic 404 page from edge	Gateway mapping or proxy rewrite	Compare response headers and test a known health route
404 only on one endpoint	Typo, missing prefix, or wrong method	Copy the path exactly and retest with curl
404 after deploy, then works later	CDN cached an error response	Purge cache for the endpoint path
Works locally, fails behind proxy	Prefix added or stripped upstream	Log upstream URI and compare to incoming URI
404 only with certain tokens	Auth or tenant routing masks routes	Test with a token that works on another endpoint

Eight-Step Checklist For The Next 404

Copy Full Request URL — Grab it from logs, not from memory.
Reproduce With Curl — Save headers and body so you can compare across tries.
Test One Known Route — Use a health or version endpoint on the same host.
Check Prefix And Slash — Verify /api, /v1, and trailing slash rules.
Match The HTTP Method — Confirm the verb and route pair exists on the server.
Identify The Replying Layer — Use headers and error shape to spot edge vs app routing.
Trace Rewrite Behavior — Confirm what the proxy or gateway forwarded upstream.
Recheck Auth Routing — Test with a token you trust on the same version.

When you collect those details, you’re no longer guessing. You know which layer replied and what URL it saw. That’s usually enough to fix the route quickly or hand the issue to a teammate without a long back-and-forth.

And if you see 404 not found in api again next week, run the same flow. The pattern repeats: a small mismatch in host, path, method, version prefix, or rewrite rules.