Errors

KontextError base class

Errors thrown by the SDK’s core operations are KontextError instances or subclasses. Each error carries structured metadata for programmatic handling.

import { isKontextError } from "@kontext-dev/js-sdk/errors";

try {
  await client.tools.execute("github:list_repos", { query: "mcp" });
} catch (err) {
  if (isKontextError(err)) {
    console.log(err.code);       // "kontext_integration_connection_required"
    console.log(err.statusCode); // 403
    console.log(err.docsUrl);    // "https://docs.kontext.security/errors/kontext_integration_connection_required"
    console.log(err.requestId);  // "req_abc123" (when available)
    console.log(err.meta);       // Additional contextual metadata
  }
}

Properties

Property	Type	Description
`code`	`string`	Machine-readable error code, typically prefixed with `kontext_`. Upstream server codes may differ.
`statusCode`	`number?`	HTTP status code when applicable
`docsUrl`	`string`	Link to the error documentation page
`requestId`	`string?`	Server request ID for debugging
`meta`	`Record<string, unknown>`	Contextual metadata (integration IDs, URLs, etc.)

Type guard

Use isKontextError() to check errors without instanceof. This works across package versions and bundler deduplication.

import { isKontextError } from "@kontext-dev/js-sdk/errors";

if (isKontextError(err)) {
  // err is typed as KontextError
}

Error codes

The SDK emits many kontext_* codes. The table below lists common codes you should handle explicitly.

Code	Status	Meaning
`kontext_authorization_required`	401	User needs to authenticate. Start the OAuth flow.
`kontext_integration_connection_required`	403	Integration needs user connection. Check `connectUrl` in meta or on the error instance. This can be OAuth or API key setup.
`kontext_oauth_token_exchange_failed`	400	OAuth token exchange failed. Inspect `errorCode` and `meta`.
`kontext_oauth_code_verifier_missing`	400	PKCE verifier is missing (usually callback state lost).
`kontext_config_missing_client_id`	—	SDK config is missing `clientId`.
`kontext_config_missing_redirect_uri`	—	SDK config is missing `redirectUri`.
`kontext_config_missing_auth_handler`	—	SDK config is missing `onAuthRequired`.
`kontext_network_error`	—	Connection or network failure. DNS resolution, timeouts, or refused connections.
`kontext_mcp_parse_error`	—	The MCP peer returned invalid JSON-RPC payloads.
`kontext_mcp_invalid_request`	—	The MCP request was structurally invalid.
`kontext_mcp_invalid_params`	—	Tool arguments or MCP call params were invalid.
`kontext_mcp_method_not_found`	—	The MCP peer does not support the requested method.
`kontext_mcp_internal_error`	500	The MCP peer failed while handling the request.
`kontext_mcp_session_expired`	401	The MCP session timed out or the transport considers it expired.
`kontext_mcp_session_error`	—	The MCP transport closed unexpectedly.
`kontext_mcp_error`	—	Fallback for other negative MCP JSON-RPC codes.
`kontext_validation_error`	400	Request validation failed. Check `validationErrors`.
`kontext_policy_denied`	403	Action denied by policy evaluation.
`kontext_not_found`	404	Requested resource does not exist.
`kontext_rate_limited`	429	Rate limit exceeded. Check `retryAfter` when available.
`kontext_server_error`	varies	Server or upstream failure. Commonly 5xx, but the client translation layer may emit this for other HTTP status codes. Retry with backoff.

Specific error classes

Import error classes from @kontext-dev/js-sdk/errors:

import {
  KontextError,
  AuthorizationRequiredError,
  IntegrationConnectionRequiredError,
  OAuthError,
  ConfigError,
  NetworkError,
  HttpError,
  translateError,
  isKontextError,
  isNetworkError,
  isUnauthorizedError,
} from "@kontext-dev/js-sdk/errors";

AuthorizationRequiredError

Thrown when no valid credentials are available. Redirect the user to sign in.

import { AuthorizationRequiredError } from "@kontext-dev/js-sdk/errors";

try {
  await client.connect();
} catch (err) {
  if (err instanceof AuthorizationRequiredError) {
    // err.authorizationUrl may contain the OAuth URL
    redirectToLogin();
  }
}

IntegrationConnectionRequiredError

Thrown when a user has not connected a required integration. The connectUrl property may contain the URL to complete integration setup (OAuth or API key flow).

import { IntegrationConnectionRequiredError } from "@kontext-dev/js-sdk/errors";

try {
  const github = await kontext.require("github", token);
} catch (err) {
  if (err instanceof IntegrationConnectionRequiredError) {
    console.log(err.integrationId);   // "github"
    console.log(err.integrationName); // "GitHub"
    console.log(err.connectUrl);      // "https://app.kontext.security/oauth/connect?session=..."
    // Open connectUrl so the user can complete required connection steps
  }
}

If you called kontext.require("github", { userId }), connectUrl is usually undefined. That path does not have a bearer token available to create a connect session on the user’s behalf.

OAuthError

Thrown when an OAuth flow fails. Covers state validation errors, token exchange failures, and provider-side rejections.

import { OAuthError } from "@kontext-dev/js-sdk/errors";

try {
  await client.auth.handleCallback(callbackUrl);
} catch (err) {
  if (err instanceof OAuthError) {
    console.log(err.errorCode);        // Provider error code
    console.log(err.errorDescription); // Human-readable description
  }
}

ConfigError

Thrown at initialization when the SDK is misconfigured. These are deterministic errors you can catch during startup.

import { createKontextClient } from "@kontext-dev/js-sdk/client";
import { ConfigError } from "@kontext-dev/js-sdk/errors";

try {
  createKontextClient({
    clientId: "",
    redirectUri: "http://localhost:3000/callback",
    onAuthRequired: () => {},
  });
} catch (err) {
  if (err instanceof ConfigError) {
    // Fix your configuration
    console.log(err.message); // "clientId is required..."
  }
}

NetworkError

Thrown on connection failures — DNS resolution errors, timeouts, refused connections.

HttpError

Thrown when the server returns an HTTP error. Includes extra fields for specific status codes.

import { HttpError } from "@kontext-dev/js-sdk/errors";

try {
  await client.applications.create({ name: "" });
} catch (err) {
  if (err instanceof HttpError) {
    console.log(err.statusCode);        // 400, 429, etc.
    console.log(err.retryAfter);        // Seconds to wait (on 429)
    console.log(err.validationErrors);  // [{ field: "name", message: "required" }]
  }
}

Detection helpers

Two utility functions for common checks:

import { isNetworkError, isUnauthorizedError } from "@kontext-dev/js-sdk/errors";

// Check for network-level failures (timeouts, DNS, refused connections)
if (err instanceof Error && isNetworkError(err)) {
  showRetryPrompt();
}

// Check for 401 / unauthorized responses
if (err instanceof Error && isUnauthorizedError(err)) {
  redirectToLogin();
}

These helpers primarily use structural checks (status codes, system error codes) with fallback string checks for compatibility with the MCP SDK, so they work with errors from any source — the SDK, fetch wrappers, or the MCP protocol.

Error translation helper

Use translateError() when you are working with low-level MCP client calls or third-party wrappers and want the same normalized KontextError surface that the higher-level SDK uses internally.

import { translateError } from "@kontext-dev/js-sdk/errors";

try {
  await mcp.callTool("search", {});
} catch (err) {
  const normalized = translateError(err);
  console.log(normalized.code, normalized.statusCode);
}

translateError() maps MCP JSON-RPC negative codes, Streamable HTTP errors, 401s, and browser/network failures into stable kontext_* codes.

Documentation

Why?

How Kontext Works

Reference

KontextError base class

Properties

Type guard

Error codes

Specific error classes

AuthorizationRequiredError

IntegrationConnectionRequiredError

OAuthError

ConfigError

NetworkError

HttpError

Detection helpers

Error translation helper

Documentation

Why?

How Kontext Works

Reference

Documentation Index

​KontextError base class

​Properties

​Type guard

​Error codes

​Specific error classes

​AuthorizationRequiredError

​IntegrationConnectionRequiredError

​OAuthError

​ConfigError

​NetworkError

​HttpError

​Detection helpers

​Error translation helper

KontextError base class

Properties

Type guard

Error codes

Specific error classes

AuthorizationRequiredError

IntegrationConnectionRequiredError

OAuthError

ConfigError

NetworkError

HttpError

Detection helpers

Error translation helper