Every auth error code in kavachOSand how to fix it

Search engines love error messages, and so will you when you paste KVCH_E_AGENT_TOKEN_EXPIRED into Google at 2am. This page exists so that search lands here, and you leave with a fix rather than a forum thread from 2019.

kavachOS surfaces structured errors everywhere: HTTP responses, SDK exceptions, audit log entries. Every error has a code field, an message field, and a docs_url that points to the relevant section of the errors reference. The families below map to how the system is organized internally. Finding the right family first cuts your debugging time in half.

{
  "error": {
    "code": "KVCH_E_AGENT_TOKEN_EXPIRED",
    "message": "The agent token has expired. Re-issue via agents.refreshToken().",
    "docs_url": "https://docs.kavachos.com/errors#KVCH_E_AGENT_TOKEN_EXPIRED",
    "request_id": "req_01HZ9XKJVBM3DQNPZ7W4LYRTF",
    "timestamp": "2026-04-02T02:14:33.081Z"
  }
}

These fire when something goes wrong with an agent credential. They are the most common category in production and nearly always fixable without a support ticket. Full model is documented in agent identity.

import { KavachError } from 'kavachos';

try {
  const result = await kavach.agents.call(agentId, payload);
} catch (err) {
  if (err instanceof KavachError && err.code === 'KVCH_E_AGENT_TOKEN_EXPIRED') {
    await kavach.agents.refreshToken(agentId);
    // retry once
    return kavach.agents.call(agentId, payload);
  }
  throw err;
}

Session errors involve human-facing authentication states. Most are benign: the user closed a tab, refreshed from a different browser, or let a session expire overnight. A few require code changes.

OAuth errors surface during the authorization code flow, token exchange, or refresh cycle. The most common culprit is a misconfigured redirect URI. If you are connecting external providers, the configuration guide covers setup steps.

MCP errors come from the OAuth 2.1 layer that kavachOS exposes for Model Context Protocol clients. If you are wiring up a tool server or an MCP client for the first time, read the MCP OAuth guide before debugging here. Most MCP errors have a structural cause that becomes obvious once you see the wire format.

// One-time registration before your first OAuth flow
const registration = await fetch(
  'https://auth.kavachos.com/.well-known/oauth/register',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_name: 'my-mcp-tool-server',
      redirect_uris: ['https://my-server.com/callback'],
      token_endpoint_auth_method: 'none', // public client
      grant_types: ['authorization_code'],
      response_types: ['code'],
    }),
  }
);

const { client_id } = await registration.json();
// Store client_id; use it in every subsequent auth request

Rate limits in kavachOS operate at four levels: global project, per-agent, per-user, and per-endpoint. When you hit a limit, the response includes a Retry-After header in seconds. The full policy is documented in the rate limits section of the API reference.

async function callWithRetry(fn: () => Promise<unknown>, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (
        err instanceof KavachError &&
        err.code.startsWith('KVCH_E_RATE_') &&
        attempt < maxAttempts
      ) {
        const retryAfter = err.retryAfter ?? 5;
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        continue;
      }
      throw err;
    }
  }
}

Every code in this reference has a known cause. If you are seeing one and the fix column does not resolve it, there are two likely explanations: either the error is masking a different root cause (check request_id in the response for the full trace), or you have found a genuine bug.

File a bug when: the error code does not match what you sent, the error fires on a request that was identical to one that succeeded seconds earlier, or the fix in this table produces the same error. The request_id from the error response is the fastest thing to include in a bug report. It lets us pull the full server-side trace within seconds.