Error catalog

Every trustmint factory-surface error is a stable THM-NNNNN code returned in an application/problem+json body. This page is a front door — the authoritative, machine-readable catalog lives in the repo and is generated, so this page links it rather than copying it.

Source of truth (do not hand-edit)

Artifact	Use
thingmake-error-catalog.md	Human-readable code reference (every code: status, title, description)
thingmake-error-catalog.json	Machine-readable form — what the SDK typed-error surface is generated from

Both are generated from services/thingmake/internal/api/errorTable by services/thingmake/cmd/error-catalog-gen. The CI drift-gate rejects any hand-edit. If you think a code is wrong, fix the source table — not the catalog.

The THM-NNNNN code scheme

Codes are bucketed by domain: the leading digits identify the bucket, so THM-2xxxx is factory-auth, THM-5xxxx is the state-changes feed, and so on. The authoritative bucket list is the catalog’s Reservations table — buckets are generated and the set grows, so read the catalog rather than memorizing a count.

At the time of writing the catalog reserves these domain buckets:

Bucket	Domain	Cross-reference
1	foundation-auth	JWT bearer auth on registration
2	factory-auth	AK/SK signing on registration
3	registrar-lifecycle	registrar approval / provisioning runs
4	thing-state-machine	illegal-transition / wrong-state (Thing lifecycle)
5	state-changes-feed	cursor polling on webhooks
6	subscriptions	webhook subscription rules on webhooks
7	identity-blacklist	the /api/v1/identity-blacklist* endpoint group
8	trust-anchor	trust-anchor delivery to the factory backend
9	internal-cross-domain-reserved	reserved (no public codes yet)

Bucket 2 — factory-auth covers FGAI-HMAC-SHA256 signing on every non-registration call (see registration). The five signing-failure codes map 1:1 to DotID’s verify-signature failure modes:

Code	DotID failure mode
THM-20110	MISSING_HEADER (a required Authorization / X-FGAI-Date / X-FGAI-Content-SHA256 header is absent)
THM-20120	INVALID_SIGNATURE (signature mismatch, or X-FGAI-Content-SHA256 ≠ body hash)
THM-20130	EXPIRED (X-FGAI-Date outside the ±5 min skew window)
THM-20140	UNKNOWN_KEY (access-key id in the Credential not recognised)
THM-20150	REPLAY (a duplicate Authorization Signature was replayed)

THM-20100 (factory-auth-failed) is the generic fallback for an unclassified signing failure. These codes are stable; this mapping is a navigation aid — the authoritative descriptions live in the generated catalog.

Bucket 7 — identity-blacklist backs the /api/v1/identity-blacklist* endpoint group (see the API reference). Its codes cover blacklist lookups (THM-70100), delta-cursor handling (THM-70110 malformed, THM-70120 older than 72h → full-sync), and snapshot-not-ready (THM-70130).

Bucket 8 — trust-anchor backs trust-anchor delivery on the ACTIVATE saga leg. Its codes are THM-TRUST-ANCHOR-FETCH-FAILED (503), THM-TRUST-ANCHOR-MALFORMED (502), and THM-TRUST-ANCHOR-REJECTED (422). See Trust-anchor delivery §5.

This table is a navigation aid, not the source of truth: if a bucket is added upstream it appears in the catalog’s Reservations table first. Always confirm against thingmake-error-catalog.md.

How the SDKs use it

Both SDKs ship a generated typed-error surface built from thingmake-error-catalog.json. On any 4xx/5xx they parse the problem body, look up the THM-NNNNN code, and return a typed error (errors.Is(err, thingmake.ErrCode...) in Go, except ...Error in Python). See the SDK quickstart.