410 when you know the resource existed and is permanently removed, and you want clients and crawlers to stop asking. 404 when you do not know, or do not wish to confirm it ever existed.

It removes URLs from a search index faster than 404, which is useful when retiring content deliberately. Neither is penalised; 410 is simply a clearer instruction.

Should a retired API version return 410?

Yes, once it is genuinely switched off - it tells integrators unambiguously that the endpoint is gone rather than broken. Pair it with a body pointing at the current version.

410 Gone

The resource existed and has been permanently removed.

Class 4xx · Client error
Retry Do not retry

What 410 means

410 is a stronger statement than 404: the resource was here, it is deliberately gone, and clients should not ask again. Where a 404 leaves open the possibility of a typo or a temporary absence, a 410 is definitive.

The practical benefit is with crawlers and caches. Search engines drop 410 URLs from their index faster than 404s, and well-behaved clients remove stored references. If you are retiring content or endpoints and want them to disappear cleanly, 410 does it faster.

It is also the right response for a deprecated API version you have actually switched off, and for content removed for legal or policy reasons - it makes the removal explicit rather than looking like a bug.

The cost is that it requires knowing the resource once existed, which usually means keeping a tombstone record. Where you cannot, 404 is the honest answer.

Should a client retry?

Permanently gone. Remove the reference - the resource is not coming back.

FAQ

410 or 404?: 410 when you know the resource existed and is permanently removed, and you want clients and crawlers to stop asking. 404 when you do not know, or do not wish to confirm it ever existed.
Does 410 help SEO?: It removes URLs from a search index faster than 404, which is useful when retiring content deliberately. Neither is penalised; 410 is simply a clearer instruction.
Should a retired API version return 410?: Yes, once it is genuinely switched off - it tells integrators unambiguously that the endpoint is gone rather than broken. Pair it with a body pointing at the current version.

Often confused with

404 Not Found The server has no resource at that URL.
301 Moved Permanently The resource has permanently moved to the URL in the Location header.