When Your REST API is a Teapot

The unusual story of HTTP error 418.

Picture: Takumi.K / PIXTA(ピクスタ)

Recently I was doing some testing for a client. The task involved using Fiddler to capture and replay requests against a certain site’s REST API. Our goal was to determine what HTTP errors might be produced that would help us with a code analysis we were expected to perform.

For the most part, the errors were what I expected. Lots of 403 Forbidden errors when I changed parameters. I even saw a few 410 (Gone) errors come my way.

But then something unexpected happened. I received an HTTP error I’d…never seen before.

Had it not been for the explanatory text, I’d have no idea what I was supposed to do with this…

HTTP 418? That was no HTTP error I’d ever heard of! How did I manage to work for two decades in this industry and never encounter this?

Naturally, I did what everyone does when confronted with weird information: I Googled it.

There is one — and I mean exactly one — protocol that uses HTTP return code 418. The Hyper Text Coffee Pot Control Protocol, or HTCPCP. (Can we call it “HTCP squared”? Yeah, you know what, let’s go with that.)

In its own words:

There is coffee all over the world. Increasingly, in a world in which
computing is ubiquitous, the computists want to make coffee. Coffee
brewing is an art, but the distributed intelligence of the web-
connected world transcends art. Thus, there is a strong, dark, rich
requirement for a protocol designed espressoly for the brewing of
coffee. Coffee is brewed using coffee pots. Networked coffee pots
require a control protocol if they are to be controlled.

So how does 418 figure into this? The error code serves an essential purpose: It tells all callers that the endpoint referenced cannot brew coffee because it is, in fact, a teapot.

2.3.2 418 I'm a teapot

Any attempt to brew coffee with a teapot should result in the error
code "418 I'm a teapot". The resulting entity body MAY be short and
stout.

After reading all that, you may feel like you’ve bean had. (See what I did there?) And you’d be right: HTCPCP is an April Fool’s joke originally dating back to 1998. It was further updated on April 1st, 2014 to address the protocol’s most glaring defect: Its inability to brew tea.

It’s deeply weird that an actual production site (in this case, a large social media site) is returning an HTTP status code that isn’t officially recognized. 418 to 420 are currently listed as IANA as “unassigned”. (Apparently, HTCPCP never made it out of the working standards group.)

However, it’s not an unheard-of practice for companies to adopt unassigned error codes for their own purposes. Twitter has done that with another unassigned code, 420, a.k.a. the “Enhance Your Calm” error status. It tells callers that they’re being rate-limited…but not to get too upset about it.

Given developers’ penchant for Easter eggs, I shouldn’t be surprised that several have snuck their way into HTTP. In the end, I guess I shouldn’t mocha big deal of it.

…I’ll, uh, see myself out.

Need help documenting YOUR obscure error codes? My company Kotobits specializes in technical writing and training with a heavy focus on DevOps and the Cloud (AWS, Azure). If you’re interested in our services, contact us today!

Owner, kotobits.com. Technical Writer and Trainer specializing in Cloud and DevOps. Tech, programming, technical writing, gadget reviews, and geek humor.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store