A Public API Error Code Taxonomy Developers Can Search

You will rewrite messages. You must not rewrite codes. Treat AUTH_TOKEN_EXPIRED and IDEMPOTENCY_BODY_MISMATCH as API surface, with the same deprecation rules as a field. A stringly-typed 'error' paragraph forces every SDK to scrape English.

Use a pattern like DOMAIN_NOUN_CONDITION, in a single case, with no spaces. Put it in a JSON error object along with a human message and, when you know the fix, a suggestion and a docs URL.

Auth, permission, not found, validation, conflict, rate limit, unavailable. Add a code when a developer would take a different next step. Do not add one for every internal exception class. Map unknown failures to a single generic code and keep the detail in your logs.

Document retry behavior on the code. A 429 and a 422 should not share a client retry loop. The taxonomy is how the SDK learns that.

The exception type in Node or Python should expose the same string the HTTP body used. If the SDK renames AUTH_TOKEN_EXPIRED to TokenError, your docs and their catch blocks diverge.

Include the code in telemetry. Grouping on HTTP status alone dumps expired tokens, bad signatures, and missing headers into one bucket. You will 'fix' the wrong one.

One URL per code, with the cause and the next call. When the probe inbox shows a spike, that page is what you update first. The draft issue can link to it so the human reviewer does not hunt.

A taxonomy nobody can search is a private enum. Put the codes in the error, in the SDK, and on a page.