Reading an Error Response

The first time a request comes back wrong, it feels like the conversation broke. It did not. An error is the conversation: the server received your request, read it, considered it, and answered — with a status, with headers, and usually with a sentence naming the exact thing to change. The only real failure available here is not reading the answer.

Think of a parcel returned to your letterbox with a sticker on it: "addressee unknown", or "postage due", and a tracking number printed underneath. The sticker is not the postal service being rude. It is the postal service being specific — it tells you which of your assumptions was wrong, and gives you a number to quote if you need to ask about this exact parcel. An API error is that sticker, and this page teaches you to read one.

An Error Has the Same Anatomy

Nothing new arrives with an error. It is a response, built from the same three parts Chapter 2 took apart: a status line with the three digits, a set of headers, and a body. The status line gives the family — the problem is on your side, or on theirs. The headers describe the body. And the body is where an API puts its story.

Here is one, in full. Vera asked for a page of stations and typed the word "nine" where a number belonged. Tandem read the request, understood it, and declined it — the status is 422, and the body names the parameter that was wrong and what it should have been.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/json

{"error": {"code": "invalid_parameter",
           "message": "limit must be an integer",
           "request_id": "req_9f2c"}}

Read that body aloud and the repair is already done: the limit has to be a whole number, so send 50 instead of a word. Beginners tend to see a wall of punctuation and look away at exactly the moment the answer is on the screen. Slowing down for the six seconds it takes to read the sentence is, honestly, the largest single improvement available on this page.

The Three Fields That Matter

Most error bodies carry three useful things, and each has a different audience. The code is a short label — invalid_parameter — that stays the same across releases and appears in the endpoint's error list in the documentation. It is meant for programs, so it never changes its wording to sound friendlier.

The message is written for a person. It is the sentence beginners skip and professionals read first, because it usually names the field, the expected type, or the missing header. Its wording can change between releases, which is exactly why the stable label sits beside it.

The request_id — req_9f2c in the example above — is your claim ticket. Tandem writes a line in its own logs for every request it handles, tagged with that id. Quote it to Jonas and he can look up this one request, out of millions, and see what his side saw. Without it, a support conversation becomes archaeology: two people guessing at which of yesterday's requests you meant.

Error Shapes Vary, the Idea Does Not

Not every API wraps its error in a field called error. Some put the three fields at the top level. Some name them type, detail, and trace_id. A few still answer with a line of plain text and nothing else — Chapter 4 already warned you that not everything is JSON, and errors are where that shows up most.

The costume changes; the reading strategy does not. Find the status. Find the machine label, if there is one. Find the human sentence. Find the identifier. If a piece is missing, note that it is missing and move on with what you have — the status line alone still tells you whose side the problem is on, which is the next two pages of this book.

The Error List Is Documentation

Chapter 6 walked you through the five bands of a reference page, and the last one was the error list: every way this endpoint can say no, each with its status and its label. That list is not a warning notice. It is the API telling you in advance the complete set of refusals it is capable of, which means every error you are ever going to meet on that endpoint has already been printed and explained.

Reading it before you integrate is how people look prescient. When the 403 arrives, they do not investigate — they recognize it, because they read the line about scopes three days ago. That is the whole trick, and it costs about two minutes per endpoint.