api reference lists endpoint that no longer exists, clients get 404 error

TL;DR

Delete the dead endpoint from the API reference source (or regenerate the reference from the live spec) and republish. Clients copy the documented path, get a 404, and file bugs against your API. Confirm the route is really gone from the server first, then remove every doc mention of it.

The error

api reference lists endpoint that no longer exists, clients get 404 error

Steps

1. Confirm the route is gone: check the server's route table or the OpenAPI spec for the path. Expected: the path is absent from both, so the 404 is real and the docs are wrong.
2. Find every doc mention: grep -rn "/v1/legacy-search" docs/ (use the actual dead path). Expected: a list of files and line numbers to fix.
3. Remove the endpoint section, or replace it with a short "Removed in v2.0 - use /v1/search" notice if users may still have it bookmarked. Expected: no full documentation remains for a dead route.
4. Rebuild the docs site. Expected: the build exits 0.
5. Search the built output for the dead path to confirm it is gone. Expected: zero hits in the built HTML.
6. Add a CI check that diffs documented paths against the OpenAPI spec so the next removal is caught automatically.

Use this when

• Docs describe an endpoint that returns 404.
• An endpoint was removed in code but its docs page still exists.
• Client bug reports trace back to a documented route that no longer works.

Not for this skill when

• The endpoint exists but returns 404 for bad input - that is API behavior, not docs drift.
• The docs are correct and the server deployment is behind - fix the deploy, not the docs.
• You are intentionally documenting a deprecated-but-live endpoint.

Variant phrasings

docs show endpoint that returns 404

Same drift, found by a user. Same fix.

removed api endpoint still documented

Same. Delete or annotate the section.

stale endpoint in api reference

Same family; "stale" here means the route is gone, not just changed.

Why it happens

Endpoint removals ship in code PRs while the docs live in a separate directory or repo, so nothing forces the two to change together. Generated references avoid this only when the generation actually runs on every change. A checked-in generated file that nobody regenerates drifts the same way.

Edge cases

• Versioned docs: the endpoint may be legitimately documented under v1 docs while removed in v2. Fix the version switcher and cross-links rather than deleting history.
• Redirects: if the old path now redirects, document the redirect target instead of deleting the page, so old bookmarks land somewhere useful.
• Search indexes: the built site search can keep surfacing the deleted page from a stale index. Rebuild the search index with the docs.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-XJsSpQx9SSc5PqSgXhRyQ