Error Responses

Clients spend as much code handling errors as handling success, and most of that code is written against whatever the first error response happened to look like. An API whose endpoints each fail in their own format forces every client to write a parser per endpoint, and an API whose errors carry stack traces hands attackers a map of its internals.

The topic starts by treating errors as part of the contract, then gives them a standard shape, problem details. An example designs the response to a request with three invalid fields, and stable error codes make errors something a program can branch on. A comparison sorts errors into those worth retrying and those that will fail every time, and a gotcha shows what an error must never contain.

The status code that sits under every error comes from the second topic in this subject. Retries of writes, and how to make them safe, come in the next section.

By the end you can read a problem details document, design the error for several invalid fields, decide what an error leaves out, and tell a client which errors to retry.