Error codes - KavachOS

KavachOS returns structured errors in the following shape:

interface KavachError {
  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 kavach.authorize(agentId, { action: 'write', resource: 'mcp:github:*' });

if (!result.allowed) {
  console.log(result.reason); // e.g. "RATE_LIMITED"
}

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

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

​Error code reference

​Agent errors

​Permission errors

​Token errors

​Delegation errors

​MCP / OAuth errors

​General errors