Machine error codes

Every 4xx response from Detent carries a stable machine-readable code field alongside a human-readable message. Switch on code, not on the text of message — the message is meant for logs and debugging, and its wording can change; code won’t.

HTTP	code	Meaning
400	invalid_request	Malformed or missing parameters
400	unknown_algorithm	algorithm is not a recognized value
400	invalid_duration	window_ms out of range
401	(none)	Missing or invalid API key
403	algorithm_not_on_plan	Algorithm not available on your plan
404	key_not_found	No rule configured for that namespace
429	monthly_hard_cap	Over the monthly anti-abuse ceiling

A stable code also means you can safely localize error handling in your own app without parsing English text — check code, then show whatever message makes sense in your users’ language.

The official SDKs, @detent/sdk (TypeScript) and detent-sdk (Python), map each code to a typed exception subclass, so you can catch a specific failure (like a plan-gating error) without string-matching at all.

See the API reference for the full request/response schemas behind each status code.