/**
* Error Types and Structured Error Definitions
* Provides consistent, machine-readable error information to AI clients
*/
/**
* Error type categories
*/
export enum ErrorType {
VALIDATION = 'validation_error',
CONFLICT = 'conflict_error', // Uniqueness, duplicates
NOT_FOUND = 'not_found_error', // 404
RATE_LIMIT = 'rate_limit_error', // 429
AUTHENTICATION = 'authentication_error', // 401
PERMISSION = 'permission_error', // 403
SERVER_ERROR = 'server_error', // 5xx
NETWORK_ERROR = 'network_error',
UNKNOWN = 'unknown_error',
}
/**
* Individual validation error details (from API responses)
*/
export interface ValidationErrorDetail {
field: string;
message: string;
expected?: string;
received?: string;
code?: string;
}
/**
* Complete error details structure
*/
export interface ErrorDetails {
type: ErrorType;
message: string;
http_status?: number;
attio_code?: string;
field?: string; // Primary field that failed
validation_errors?: ValidationErrorDetail[];
suggestions?: string[];
retryable: boolean;
retry_after?: number; // Seconds to wait (for 429)
original_error?: unknown; // For debugging
}
/**
* Success response wrapper
*/
export interface ToolSuccess<T> {
success: true;
data: T;
}
/**
* Error response wrapper
*/
export interface ToolError {
success: false;
error: ErrorDetails;
timestamp: string;
}
/**
* Union type for tool results
*/
export type ToolResult<T> = ToolSuccess<T> | ToolError;
/**
* Custom error classes for proper error categorization
*/
export class ConfigurationError extends Error {
readonly errorType = ErrorType.VALIDATION;
constructor(message: string) {
super(message);
this.name = 'ConfigurationError';
}
}
export class ValidationError extends Error {
readonly errorType = ErrorType.VALIDATION;
readonly field?: string;
constructor(message: string, field?: string) {
super(message);
this.name = 'ValidationError';
this.field = field;
}
}
