It makes sense to include so it's obvious in the readable HTTP request response. We use readable URLs and header names for the same purpose: So it is inspectable and understandable from that text format. You may leave deprecation information out, but then you're missing part of the resource description that you're addressing with the URL/URI.

Given a defined header it also allows you to add tooling and automation. There's no need for manual reading.

Also, TIL that the IETF deprecated the X- prefix more than 10 years ago. Seems like that one didn’t pan out.

Can you elaborate on that? The X- prefix is supposedly only a recommendation, and intended to be used in non-standard, custom, ah-hoc request headers to avoid naming conflicts.

Taken from https://datatracker.ietf.org/doc/html/rfc6648

In short, although in theory the "X-" convention was a good way to avoid collisions (and attendant interoperability problems) between standardized parameters and unstandardized parameters, in practice the benefits have been outweighed by the costs associated with the leakage of unstandardized parameters into the standards space.

I still work on software that extendively uses X- headers.

You can simply log this response. Then developers know to replace that call in the next version. If you have unit tests that look for this then you can be sure that your next version is not using any deprecated API calls.