A production request starts returning 404 Not Found. The application has not deployed recently, and the integration worked yesterday. Has the provider removed the endpoint, or is your application sending a different request than you think?
Treat removal as a hypothesis, not a diagnosis. A missing route, incorrect resource identifier, changed credentials, environment mismatch, or gateway rule can produce similar symptoms. The immediate job is to preserve evidence, establish the scope, and keep recovery attempts from creating additional problems.
Our earlier article on how API changes break applications that haven’t changed explains the dependency problem. This runbook addresses the operational question: what should you check when an endpoint appears to disappear?
1. Record the request before changing anything
Capture one failing request and, if available, one previously successful request. Compare what actually crossed the network, not just the URL assembled in application code.
Record:
- HTTP method, host, path, and relevant query parameters.
- Environment, region, API version, and tenant or account context.
- Authentication mechanism and credential identity, without storing secrets.
- Response status, relevant headers, sanitized body, and provider request ID.
- Timestamp, application release, and the workflow making the call.
Keep resource identifiers protected where necessary, but preserve enough structure to distinguish a missing route from a missing resource. GET /v1/invoices/123 and POST /v1/invoices are different operations, even though they share a path prefix.
Inspect redirect history and the final destination when available. A configured base URL is not proof that the request reached the intended host. Avoid placing tokens, customer data, or full sensitive payloads in incident tickets.
2. Interpret 404 and 410 without overclaiming
The HTTP semantics specification for 404 Not Found says the origin server either did not find a current representation of the target resource or is unwilling to disclose that one exists. It explicitly does not establish whether the condition is temporary or permanent.
That leaves several possibilities:
- The resource identifier is wrong or the resource was deleted.
- The route or API version is unavailable.
- The account cannot see the resource.
- The request reached the wrong environment or gateway.
- The provider removed the endpoint.
410 Gone is stronger evidence: it indicates that access is no longer available and the condition is likely permanent. Even then, determine whether the response concerns one resource, an entire operation, or an intermediary’s routing decision.
Do not turn either status into a migration plan without checking context. A response body naming a retired API version is useful evidence; a generic HTML error page may instead point toward a proxy or routing layer. Also inspect cache-related headers: a cached negative response can complicate verification after a correction.
3. Compare authentication and environment
Before rewriting the integration, compare the failing request with a known-good configuration.
Check the exact hostname, region, version prefix, path casing, trailing slash behavior, and resource identifier. Then inspect credential identity, token audience, scopes, tenant selection, and recent secret rotation. Some APIs deliberately return 404 rather than reveal a resource to an unauthorized caller.
Environment mismatches are particularly misleading. A production identifier may not exist in a sandbox. A regional host may not contain resources created elsewhere. A token can be valid but belong to the wrong account.
Change one variable at a time. If you replace the token, host, version, and resource identifier together, a successful response will not tell you which assumption failed.
A direct request outside the application can help separate client behavior from provider behavior. The tradeoff is fidelity: an ad hoc command may omit headers, proxy settings, or account context. Match those details deliberately, and use a read-only operation where possible.
4. Check the provider’s change record
Look for deprecation notices, migration guides, API reference updates, changelog entries, and status-page incidents. Search for the exact method and path, not just the provider’s name.
Verify whether the notice applies to your API version, region, account type, and effective date. A replacement endpoint might require different permissions, pagination, identifiers, or response handling. Similar naming does not make it a drop-in replacement.
If documentation is ambiguous, send provider support a narrow evidence package: sanitized request details, timestamps, request IDs, affected environment, and the first known failure. Ask whether the operation was retired or whether account-specific access changed.
The tradeoff is speed versus certainty. Waiting for support may delay recovery; migrating on an assumption can introduce a second failure. Keep a reversible mitigation separate from the permanent fix.
5. Contain the failure without unsafe retries
Do not blindly retry non-idempotent requests. A timeout or ambiguous response may occur after a write succeeded, and a repeated submission can create duplicate business actions. A subsequent 404 does not settle what happened to an earlier attempt.
For writes, inspect the provider’s documented idempotency behavior and any available operation-status or reconciliation mechanism. Do not assume that adding an arbitrary header makes a request safe, or that switching to a replacement endpoint preserves deduplication behavior.
Read-only requests are generally easier to replay safely, but repeated requests will not repair a removed route. Use bounded checks rather than an unending retry loop.
Possible containment measures include pausing the affected worker, disabling the affected action, or preserving work for later processing. Each has a cost: delays, reduced functionality, or backlog growth. Choose explicitly, assign an owner, and tell operators what remains available.
6. Fictional example: an invoice export stops working
Consider a fictional SaaS application whose export worker calls GET /v1/invoices/{id}/download. It starts receiving 404 responses. The team initially suspects endpoint removal.
The incident owner records the method, configured host, versioned path, account identity, and request IDs. A comparison shows that production and sandbox settings are unchanged. A permitted read-only check confirms that the invoice itself remains accessible, narrowing the question to the download operation or its access rules.
The provider’s changelog describes retirement of that operation and identifies a replacement export workflow. That is stronger evidence of removal than the status code alone.
The team pauses repeated download attempts while preserving pending export jobs. It maps the consumers: a scheduled export worker, a user-facing download action, and a support procedure. Each needs verification; fixing the worker alone would leave the download action broken.
Before releasing a replacement, the team checks authorization, export readiness, file handling, and error behavior. It records the old operation as confirmed unavailable, the replacement worker as tested, and the user-facing action as still unverified. No single successful request is treated as proof that every workflow recovered.
7. Close with an evidence checklist
Use this checklist before declaring the incident resolved:
- [ ] Exact method, host, path, environment, and account recorded.
- [ ] Resource absence distinguished from route absence where possible.
- [ ] Authentication and configuration differences checked.
- [ ] Provider notices matched to the affected operation.
- [ ] Unsafe retries stopped and uncertain writes reconciled.
- [ ] Affected consumer workflows and owners identified.
- [ ] Replacement behavior tested beyond the success status.
- [ ] Confirmed, ruled-out, and unknown effects recorded separately.
- [ ] Temporary mitigations assigned a review or removal point.
One useful next step: take the failing operation and list every consumer workflow that depends on it, with one targeted check and one owner per workflow. That turns an endpoint investigation into a bounded recovery plan.
GhostImpact helps teams understand API changes, map producer-to-consumer dependencies, and investigate potential downstream impact. It supports that investigation; it does not replace testing or engineering judgment. Explore GhostImpact or start a project conversation.