Errors

All SDK methods throw ConfigureError on failure. Each error has a machine-readable code for programmatic handling, structured metadata for retry logic and suggested actions, and an optional statusCode from the HTTP response.

Import

import { ConfigureError, ErrorCode, classifyError } from 'configure';

ConfigureError

class ConfigureError extends Error {
  readonly code: ErrorCodeValue;
  readonly statusCode?: number;
  readonly message: string;
  readonly type?: string;
  readonly param?: string | null;
  readonly retryable?: boolean;
  readonly suggestedAction?: string | null;
  readonly docUrl?: string | null;
  readonly retryAfter?: number | null;
  readonly requestId?: string;

  constructor(code: ErrorCodeValue, message: string, statusCode?: number, details?: ErrorDetails);
  static fromResponse(status: number, body: Record<string, unknown>): ConfigureError;
  static fromCatch(error: unknown, fallbackMessage: string): ConfigureError;
}

Property	Type	Description
code	ErrorCodeValue	Machine-readable error code (see table below).
statusCode	number | undefined	HTTP status code from the API, if applicable.
message	string	Human-readable error description.
type	string | undefined	Backend error type (e.g., "authentication_error", "tool_error").
param	string | null	The field or parameter that caused the error.
retryable	boolean | undefined	Whether the same request might succeed if retried.
suggestedAction	string | null	Machine-readable next action (e.g., "reauthenticate", "connect_tool").
docUrl	string | null	Link to error documentation.
retryAfter	number | null	Seconds to wait before retrying (rate limits).
requestId	string | undefined	Backend request ID for debugging and support.

Error Codes

Code	HTTP Status	Cause	Solution
API_KEY_MISSING	N/A	No API key provided to ConfigureClient.	Pass the key as the first argument or set CONFIGURE_API_KEY env var.
AUTH_REQUIRED	401, 403	Token is missing, invalid, or expired.	Re-authenticate via auth.verifyOtp().
INVALID_INPUT	400	Input failed validation before reaching the API.	Check parameter format (e.g., E.164 phone, 6-digit OTP).
TOOL_NOT_CONNECTED	400	The requested tool is not connected for this user.	Prompt the user to connect the tool via tools.connect().
ACCESS_DENIED	403	Not authorized for this resource (distinct from AUTH_REQUIRED).	Check the user's permission settings or agent access.
TOOL_ERROR	varies	Tool operation failed (provider error, misconfiguration).	Retryable — retry after a short delay.
PAYMENT_REQUIRED	402	Billing or quota limit reached.	Upgrade your plan in the dashboard.
NETWORK_ERROR	N/A	Network request failed (DNS, connection refused, etc.).	Check connectivity, retry with backoff.
RATE_LIMITED	429	Too many requests.	Back off and retry after the cooldown period. Use retryAfter if available.
NOT_FOUND	404	Resource not found.	Verify the path, user ID, or resource exists.
SERVER_ERROR	500+	Server-side failure.	Retry with backoff. If persistent, check the status page.
TIMEOUT	N/A	Request timed out.	Increase the timeout option or retry.

Usage

import { ConfigureClient, ConfigureError, ErrorCode } from 'configure';

const client = new ConfigureClient('sk_your_api_key');

try {
  const profile = await client.profile.get(token, userId);
} catch (error) {
  if (error instanceof ConfigureError) {
    switch (error.code) {
      case ErrorCode.AUTH_REQUIRED:
        // error.suggestedAction === 'reauthenticate'
        console.log('Please log in again');
        break;
      case ErrorCode.TOOL_NOT_CONNECTED:
        // error.suggestedAction === 'connect_tool'
        // error.param === 'tool'
        console.log('Please connect the required tool');
        break;
      case ErrorCode.ACCESS_DENIED:
        // error.suggestedAction === 'check_permissions'
        console.log('Permission denied');
        break;
      case ErrorCode.RATE_LIMITED:
        // error.retryable === true
        // error.retryAfter — seconds to wait
        console.log('Rate limited, retrying...');
        break;
      case ErrorCode.PAYMENT_REQUIRED:
        // error.suggestedAction === 'upgrade_plan'
        console.log('Quota exceeded');
        break;
      case ErrorCode.NETWORK_ERROR:
      case ErrorCode.TIMEOUT:
        // error.retryable === true
        console.log('Network error, retrying...');
        break;
      default:
        console.error(`Error [${error.code}]: ${error.message}`);
    }
  }
}

classifyError()

Classifies any caught error into a ConfigureError with a friendly user-facing message. Works with SDK errors, Anthropic errors, network errors, or plain strings. See the Error Handling guide for full examples and the friendly message table.

import { classifyError } from 'configure';

const classified = classifyError(error);
// classified.code — e.g., ErrorCode.RATE_LIMITED
// classified.message — e.g., "taking a breather — try again in a moment."

Input Validation

The SDK validates inputs before making API calls and throws ConfigureError with code INVALID_INPUT:

• Phone numbers must be in E.164 format (e.g., +14155551234).
• OTP codes must be exactly 6 digits.
• Storage paths must not contain ../ (path traversal).
• Tool types must be one of: gmail, calendar, drive, notion.
• Required parameters must not be empty or null.

// These throw ConfigureError with INVALID_INPUT before any network call
client.auth.sendOtp('not-a-phone');      // Invalid E.164 format
client.auth.verifyOtp('+1415555', '12');  // OTP must be 6 digits
client.self.write('../../../etc/passwd', 'x');  // Path traversal blocked