Uh, before we all start getting our payment APIs to return 402s in a million different and incompatible scenarios, I'd urge everyone to remember what "reserved" means". It means "don't use this until we've defined it properly".
Actually, it's not used that much on high-volume systems. That's because a LOT of platforms treat 4xx as "user error" and will treat them as fatal.
So call goes from TelcoA, to Reseller1. Reseller1 cleverly returns 402. TelcoA stops and doesn't failover, returns error to customer. TelcoA is unhappy, because they wanted to continue the call to Reseller2.
Source: I work in wholesale telecom and this is exactly what every larger customer asks for. They must get a 5xx error (sometimes a 503 specifically), or their side won't continue hunting the call.
402 and all the other fun stuff might be used in a more pure SIP environment, but I doubt it's used in any sort of significant % of actual SIP deployments. Actually, just like most of the spec. It's either confusing, useless ("Retry-After: 300 (I'm in a meeting)", or a security hole.
Shopify return 402 for a client's site when they haven't paid. I'm not sure of the exact criteria (grace period etc.).
It's very helpful as a provider of services to Shopify stores to know 'this prospect may not pay'. The average shopper doesn't know HTTP codes too, so it avoids tarnishing the shop's reputation if it was just an oversight.
This is exactly what I've used the 402 code for. Some API routes are available to all users, but others require paid access. If a freemium user attempts to access API routes behind the "paywall" I return the 402 code.
This gives more information than a 401 or 403, but agreed that it's use is still limited. Would make sense to return a 402 along with a redirect to a payment page.
I think a 402 with a typed "Link" response header field of "payment" (per http://tools.ietf.org/html/rfc5988) would probably be the most appropriate no?
Speaking of little-known status codes: 503 Service Unavailable should always be used in maintenance scenarios. 404s tell users to delete the bookmark and Google to remove the page from the index.
On bbot.org I return 410 on robots.txt, for tedious ideological reasons. Doesn't stop spiders requesting it, of course, since that check is probably hard-coded.
I did mean 404. When people or spiders encounter a 404 twice, they will assume the resource is Gone (although a 404 doesn't technically tell them that it is, sure, sorry I didn't make that clearer: "No indication is given of whether the condition is temporary or permanent.")
A real 410 would obviously be even worse, but that won't usually happen by accident. When my server/app crashes and I'm working on restoring the configuration, in the meantime, it will usually show a 404. And that's bad.
I once led a scraping proxy project that required users to be registered in order to access it. When someone unauthorised tried to use it 402 was returned with a message body giving a bank account number that was a concatenation of consecutive prime numbers. I wonder whether I made someone rich by accident.
If your IT director forgets to pay Artifactory, you'll have to turn on verbose logging in maven to see that they're returning a 402 when you try to build your code.
Funny this should show up today. Just got this error yesterday on one of our properties from maxmind, and sure enough, it was a payment issue. First time I'd seen it in use.
