Skip to main content
theAuth returns structured errors in the following shape:
All SDK functions that can fail return a Result<T> discriminated union rather than throwing:
For REST API calls, errors are returned as JSON with the corresponding HTTP status code:

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

theauth.authorize() does not return HTTP-style codes. It returns { allowed, reason, auditId, code } where code is one of the lowercase decision codes above and reason is free-form text. Agent calls such as agent.create() (at the maxPerUser limit), agent.update(), agent.revoke() and agent.rotate() throw a plain Error with a descriptive message, so there are no AGENT_* or PERMISSION_* REST codes to branch on. Use the decision codes for authorization outcomes. The tables below list the uppercase codes that core, the adapters and the gateway really emit.
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 as Result 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 returns Result 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

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.
Last modified on October 19, 2026