Why our error messages have a number

Every error response from Digest looks like this:

{ "error": { "code": "E2041", "message": "cursor has expired", "docs": "https://docs.digest.example/errors/E2041" } }

The code is the part that matters. Here is why.

Messages change; codes do not

A message is for a person reading a log. We reword them when they are unclear. A client that matches on message text breaks when we do. A code is a contract: E2041 has meant "cursor expired" since 1.0 and will mean it in 4.0.

Codes are searchable

Every code has a page. The page says what it means, why it happens, and what to do. Support answers a question about E2041 by sending the link.

How we keep them stable

• Codes live in one file. Adding one is a pull request that requires a docs page in the same change.
• Removing one is not allowed. A code that no longer occurs stays in the file, marked retired, so it can never be reused for something else.
• A test fails if a code is returned that is not in the file.

Ranges

E1xxx is authentication, E2xxx is requests, E3xxx is limits, E5xxx is us. If you see an E5, it is our fault and the status page will already say so.