Prompt and scope
A public API version and web resource are permanently removed. The team wants clients to stop retrying while preserving a migration path and audit evidence. Compare 410, 404, 301/308, and 403, then design responses, caching, a shutdown window, and monitoring.
This is an HTTP semantics and product-lifecycle question. The version and retirement date are assumptions, not market claims.
What the interviewer is testing
- Whether you distinguish “currently unavailable” from “known permanently removed.”
- Whether you understand 410’s effects on caching and clients.
- Whether migration, authorization, privacy, and audit have one lifecycle model.
- Whether you avoid using a status code to hide an unknown outage or routing bug.
Clarifying questions to ask
- Is the resource permanently deleted, temporarily offline, or moved to a stable URI?
- Are caches, search indexes, SDK retries, or offline clients involved?
- Do retention, compliance, or audit rules constrain deletion?
- Can old clients understand 410 and migration information in the error body?
- Should unauthorized users see a 404 to hide resource existence?
A 30-second answer
“410 means the server knows the target existed but has permanently removed it; 404 only says no current representation is available. Use 301 or 308 when a stable replacement exists, and 403 or a security-driven 404 for authorization. Announce retirement through docs, SDKs, and a migration window, then return a 410 with a stable code and documentation link using deliberate cache controls. Clients should stop pointless retries. Deletion remains auditable, and I measure retirement traffic, cache behavior, and migration success.”
Step-by-step design
1. Build a state decision table
Use 410 for a permanently removed resource that will not be served again. Use 404 when existence or future availability is unknown, and a redirect when the resource has a clear new URI. Whether an authorization failure is 403 or a disguised 404 depends on the threat model and disclosure policy.
2. Design the 410 response
Include a stable error code, request ID, retirement documentation, and an optional replacement hint. Do not expose sensitive deletion reasons or database state. An API can use a structured error body; a web page can provide an accessible migration explanation. Both must retain machine-readable 410 semantics.
HTTP/1.1 410 Gone
Cache-Control: max-age=3600
Content-Type: application/problem+json
Link: <https://api.example/migrations/v1>; rel="deprecation"3. Handle caching and clients
410 is generally heuristically cacheable unless the method definition or explicit cache controls say otherwise. Evaluate false-revocation risk, CDN behavior, and local client caches before choosing a lifetime. If the decision can change, start short and extend gradually. A client seeing 410 should stop useless retries and enter migration or user-notice logic.
4. Plan the retirement window
Publish the deprecation date in documentation, SDKs, and response headers, then segment usage by caller, version, and traffic. During the window serve successfully with migration signals; afterward return 410. High-risk writes can be rejected first while a read-only migration endpoint remains. Define rollback checkpoints before each change.
5. Preserve deletion and privacy evidence
410 does not prove physical deletion from storage. Record resource identity, approval, deletion time, retention policy, replacement entry point, and response version. Never retain deleted sensitive content in logs. If compliance requires delayed deletion, expose 410 while internal retention and cleanup continue under their own controls.
6. Monitor classified outcomes
Split 410 by resource, client, SDK version, cache hit, and migration click to distinguish real retirement from a routing bug. Compare 404, 403, redirect chains, retry volume, and support tickets. If 410 spikes unexpectedly, stop extending cache lifetimes and roll back the configuration while investigating.
Model high-quality answer
“I first establish the resource state. Known permanent removal gets 410; unknown or temporary absence gets 404; a clear replacement gets 301 or 308; authorization uses 403 or a security-driven 404. I announce a migration window through docs, SDKs, and headers, then return 410 with a stable code, request ID, and documentation link using cautious caching. Clients stop retrying. Deletion and retention are audited separately, while metrics cover 410 sources, caches, migration success, and rollback triggers.”
Common mistakes
- Returning 410 for every deletion → temporary or unknown states look permanent → classify the resource state.
- Returning 410 despite a replacement → clients lose migration → use 301/308 and documentation.
- Caching 410 forever → false retirement is hard to undo → set and extend TTL by risk.
- Treating 410 as proof of physical deletion → retention and compliance are skipped → audit cleanup separately.
- Watching only a total → old SDK failures remain hidden → segment by version, resource, and cache.
Follow-up questions and responses
What is the essential difference between 410 and 404?
410 says the server confirms that the resource existed and is permanently removed. 404 says neither whether it existed nor whether it may appear later. Choosing 410 makes a stronger promise about retry, caching, and migration behavior.
Can a 410 include a replacement link?
Yes, it can provide documentation or a migration entry point, but it must not pretend that the replacement is the current resource. The client still rechecks authorization, version, and data mapping.
Why might an unauthorized user receive 404?
If revealing that a resource exists leaks sensitive information, the server may hide existence with 404 under its threat model. Authorized callers should still receive consistent and auditable lifecycle semantics.