Package com.tnsai.tools.spi

Class ToolException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.tnsai.exceptions.TnsAIException

com.tnsai.tools.spi.ToolException

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ToolAuthenticationException, ToolAuthorizationException, ToolConfigurationException, ToolConflictException, ToolExternalServiceException, ToolInputException, ToolNotFoundException, ToolRateLimitException, ToolResultSerializationException, ToolTimeoutException, ToolUnexpectedException, ToolUserCanceledException

public class ToolException
extends TnsAIException

Exception thrown when a tool execution fails.

Provides structured error information including:

• Error type classification (ToolException.ErrorType)
• Tool name and query that caused the error
• HTTP status code (for API errors)
• Retry eligibility flag
• Timestamp of the error
• Additional context attributes

Usage Example

 // Simple usage
 throw new ToolException("API rate limit exceeded", ErrorType.RATE_LIMITED);

 // Full context
 throw ToolException.builder("Connection timeout")
     .type(ErrorType.TIMEOUT)
     .toolName("brave_search")
     .query("quantum computing")
     .retryable(true)
     .attribute("timeout_ms", 30000)
     .build();
 

See Also:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ToolException.Builder	Builder for ToolException.
static enum	ToolException.ErrorType	Error type classification.

Constructor Summary

Constructors

Constructor	Description
ToolException(String message)	Create a simple tool exception.
ToolException(String message, ToolException.ErrorType errorType)	Create a tool exception with error type.
ToolException(String message, ToolException.ErrorType errorType, Throwable cause)	Create a tool exception with error type and cause.
ToolException(String message, Throwable cause)	Create a tool exception with cause.

Method Summary

Modifier and Type	Method	Description
static ToolException	apiError(String toolName, int statusCode, String message)	Create an API error.
static ToolException.Builder	builder(String message)	Create a builder for ToolException.
static ToolException	configurationError(String toolName, String envVar)	Create a configuration error (e.g., missing API key).
<T> T	getAttribute(String key)
Map<String,Object>	getAttributes()
String	getDetailedMessage()	Get a detailed error message including all context.
ToolException.ErrorType	getErrorType()
int	getHttpStatusCode()
String	getQuery()
Instant	getTimestamp()
String	getToolName()
boolean	isRetryable()	Checks if this error is retryable.
static ToolException	networkError(String toolName, Throwable cause)	Create a network error.
static ToolException	parseError(String toolName, String message, Throwable cause)	Create a parse error.
static ToolException	timeout(String toolName, long timeoutMs)	Create a timeout error.
String	toString()
static ToolException	validationError(String toolName, String message)	Create a validation error.

Methods inherited from class com.tnsai.exceptions.TnsAIException

getContext, getErrorCode, getMaxRetryAttempts, getMessage, getSuggestedRetryDelayMs, getThrownAt, wrap

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

ToolException

public ToolException(String message)

Create a simple tool exception.

ToolException

public ToolException(String message,
 Throwable cause)

Create a tool exception with cause.

ToolException

public ToolException(String message,
 ToolException.ErrorType errorType)

Create a tool exception with error type.

ToolException

public ToolException(String message,
 ToolException.ErrorType errorType,
 Throwable cause)

Create a tool exception with error type and cause.

Method Details

builder

public static ToolException.Builder builder(String message)

Create a builder for ToolException.

validationError

public static ToolException validationError(String toolName,
 String message)

Create a validation error.

configurationError

public static ToolException configurationError(String toolName,
 String envVar)

Create a configuration error (e.g., missing API key).

apiError

public static ToolException apiError(String toolName,
 int statusCode,
 String message)

Create an API error.

timeout

public static ToolException timeout(String toolName,
 long timeoutMs)

Create a timeout error.

networkError

public static ToolException networkError(String toolName,
 Throwable cause)

Create a network error.

parseError

public static ToolException parseError(String toolName,
 String message,
 Throwable cause)

Create a parse error.

getErrorType

public ToolException.ErrorType getErrorType()

getToolName

public String getToolName()

getQuery

public String getQuery()

getHttpStatusCode

public int getHttpStatusCode()

isRetryable

public boolean isRetryable()

Description copied from class: TnsAIException

Checks if this error is retryable. Retryable errors are typically transient (network issues, rate limits, server errors).

Overrides:

isRetryable in class TnsAIException

Returns:

true if the operation can be retried

getTimestamp

public Instant getTimestamp()

getAttributes

public Map<String,Object> getAttributes()

getAttribute

public <T> T getAttribute(String key)

getDetailedMessage

public String getDetailedMessage()

Get a detailed error message including all context.

toString

public String toString()

Overrides:

toString in class Throwable