Error codes - theAuth

theAuth returns structured errors in the following shape:

interface TheAuthError {
  code: string;    // machine-readable error code
  message: string; // human-readable description
  details?: Record<string, unknown>; // additional context
}

All SDK functions that can fail return a Result<T> discriminated union rather than throwing:

const result = await theauth.authorize(agentId, { action: 'write', resource: 'mcp:github:*' });

if (!result.allowed) {
  console.log(result.reason); // e.g. 'Rate limit exceeded: 20/20 calls per hour for resource "mcp:deploy:staging"'
}

For REST API calls, errors are returned as JSON with the corresponding HTTP status code:

{
  "code": "AGENT_NOT_FOUND",
  "message": "Agent agt_01abc does not exist or has been revoked."
}

Error code reference

theauth.authorize() and theauth.delegate() do not return the permission and delegation codes in the tables below. authorize() returns { allowed, reason, auditId } where reason is free-form text (for example No permission grants agent "x" access to "write" on "mcp:github:repos"), and delegate() throws a plain Error with a descriptive message (a subset violation or a depth overrun). Treat the Agent, Permission, Token, and Delegation tables as a reference vocabulary for your own HTTP layer, not as values the TypeScript core emits. The MCP module returns Result errors with codes such as INVALID_CLIENT, INVALID_GRANT, LOGIN_REQUIRED, INVALID_TOKEN, TOKEN_EXPIRED, INVALID_AUDIENCE, INVALID_ISSUER, INSUFFICIENT_SCOPE, UNAUTHORIZED, and SERVER_ERROR.

Agent errors

Code	HTTP status	Description
`AGENT_NOT_FOUND`	404	No agent with the given ID exists.
`AGENT_LIMIT_EXCEEDED`	422	The user has reached their `maxPerUser` agent limit.
`AGENT_REVOKED`	403	The agent has been explicitly revoked and cannot be used.
`AGENT_EXPIRED`	403	The agent’s `expiresAt` is in the past.

Permission errors

Code	HTTP status	Description
`PERMISSION_DENIED`	403	The agent does not have a permission matching the requested resource and action.
`RATE_LIMITED`	429	The agent has exceeded its `maxCallsPerHour` constraint for this resource.
`OUTSIDE_TIME_WINDOW`	403	The current time falls outside the permission’s `timeWindow` constraint.
`IP_NOT_ALLOWED`	403	The request IP is not in the permission’s `ipAllowlist`.
`REQUIRES_APPROVAL`	202	The action requires human approval (`requireApproval: true`). An approval request has been created.

Token errors

Code	HTTP status	Description
`INVALID_TOKEN`	401	The token cannot be verified (bad signature, malformed, or unknown).
`TOKEN_EXPIRED`	401	The token’s `exp` claim is in the past.

Delegation errors

Code	HTTP status	Description
`DELEGATION_DEPTH_EXCEEDED`	422	The delegation would exceed the `maxDepth` limit.
`INSUFFICIENT_PERMISSIONS`	403	The delegating agent is attempting to grant permissions it does not hold.
`DELEGATION_NOT_FOUND`	404	No delegation with the given ID exists.
`DELEGATION_EXPIRED`	403	The delegation chain’s `expiresAt` is in the past.

MCP / OAuth errors

Code	HTTP status	Description
`MCP_CLIENT_NOT_FOUND`	401	The OAuth `client_id` is not registered.
`MCP_INVALID_GRANT`	400	The authorization code or refresh token is invalid, expired, or already consumed.
`MCP_INVALID_REDIRECT_URI`	400	The `redirect_uri` does not match the registered client.
`MCP_PKCE_FAILED`	400	The `code_verifier` does not match the stored `code_challenge`.
`MCP_SCOPE_INSUFFICIENT`	403	The token does not carry the required scopes for this endpoint.
`MCP_CLIENT_DISABLED`	403	The OAuth client has been disabled by an administrator.

General errors

Code	HTTP status	Description
`BAD_REQUEST`	400	The request body or parameters failed validation.
`UNAUTHORIZED`	401	No valid credential was provided.
`FORBIDDEN`	403	The credential is valid but does not have access to this resource.
`NOT_FOUND`	404	The requested resource does not exist.
`INTERNAL_ERROR`	500	An unexpected error occurred. Check server logs for details.

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.

​Error code reference

​Agent errors

​Permission errors

​Token errors

​Delegation errors

​MCP / OAuth errors

​General errors

​Related