Result<T> discriminated union rather than throwing:
Decision codes
authorize(), authorizeByToken() and policy.evaluate() return a machine-readable code next to the free-form reason. The set is closed: DECISION_CODES is exported from @glinr/theauth, with the DecisionCode type, isDecisionCode() and violationTypeOf(). Branch on code, never on reason text.
code is optional on the AuthorizeResult type so results you build by hand still compile, but core always sets it. PolicyDecision.code is always present.
Error code reference
REST errors from the adapters and the gateway use{ "error": { "code", "message" } }. MCP OAuth endpoints use the RFC 6749 wire shape { "error": "invalid_grant", "error_description": "..." }, with the code lowercased.
Delegation errors
theauth.delegate() throws a DelegationError (a typed Error with a code). The framework adapters map it to HTTP 400 and send code through as the REST error code.
User errors
theauth.user.create() throws a UserError. Branch on code.
Hook errors
Agent tool errors
Token errors
Returned by the MCP token validator asResult errors, and by mcp.requireScopes as a typed denial (status, error.code, error.message, and rejected for a token whose signature verified). Over HTTP they are a 401 with a WWW-Authenticate: Bearer error="invalid_token", error_description="...", resource_metadata="..." challenge (a request with no token gets the same header without error). The 401 body is a JSON-RPC error with code -32001 and the reason in error.data.code.
MCP and OAuth errors
The MCP module returnsResult errors with these codes. The token, registration, revocation and introspection endpoints answer 401 for INVALID_CLIENT and 400 for the rest, with the exceptions in the table.
requireMcpAuth, requireScopes and gateway policies with requiredScopes answer a scope shortfall with 403 and a WWW-Authenticate challenge carrying error="insufficient_scope", the missing scope and resource_metadata. The body lists required_scopes and current_scopes. The step-up helper adds an upgrade_url so the client can re-authorize with the extra scopes.
General errors
Related
API reference
Full REST endpoint reference with request and response shapes.
Agent identity
Agent creation, rotation, and revocation that produce these error codes.
Permissions
Permission and delegation errors explained in context.
Test utilities
Assert on error codes in unit tests without a real database.