Package org.springframework.ai.model.tool

Class ToolCallLimitExceededException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.springframework.ai.model.tool.ToolCallLimitExceededException

All Implemented Interfaces:

Serializable

public class ToolCallLimitExceededException
extends RuntimeException

Thrown by DefaultToolCallingManager when a configured tool call limit is exceeded and ToolCallLimitBehavior.THROW is in effect.

Carries the ToolExecutionResult assembled from whichever tool calls in the current batch already executed successfully before the limit was hit, so a caller can still produce a coherent response instead of discarding completed work.

Since:

2.0.1

Author:

Christian Tzolov

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	FINISH_REASON	Generation.getMetadata() finish reason set on the Generation built by buildGeneration(), distinguishing a forcibly aborted turn from a regular returnDirect completion.
static final String	METADATA_PARTIAL_TOOL_RESPONSES	ChatGenerationMetadata key under which the ToolResponseMessage.ToolResponses that completed successfully in the current batch before the limit was hit are attached to the Generation built by buildGeneration().

Constructor Summary

Constructors

Constructor	Description
ToolCallLimitExceededException(@Nullable String toolName, int limit, ToolExecutionResult partialToolExecutionResult)

Method Summary

Modifier and Type	Method	Description
Generation	buildGeneration()	Builds a single Generation representing this exception, so that a limit breach is never mistaken for one of several equally valid answers.
int	getLimit()	The configured limit that was exceeded.
ToolExecutionResult	getPartialToolExecutionResult()	The result assembled from the tool calls already executed in the current batch, including a synthesized error response for the call that exceeded the limit.
@Nullable String	getToolName()	The name of the tool whose per-tool limit was exceeded, or null when the total per-turn limit was exceeded instead.

Methods inherited from class java.lang.Throwable

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

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Details

FINISH_REASON

public static final String FINISH_REASON

Generation.getMetadata() finish reason set on the Generation built by buildGeneration(), distinguishing a forcibly aborted turn from a regular returnDirect completion.

See Also:

• Constant Field Values

METADATA_PARTIAL_TOOL_RESPONSES

public static final String METADATA_PARTIAL_TOOL_RESPONSES

ChatGenerationMetadata key under which the ToolResponseMessage.ToolResponses that completed successfully in the current batch before the limit was hit are attached to the Generation built by buildGeneration(). Keeping them in metadata - rather than as separate, sibling Generations - avoids mixing successful tool output with the error message as if they were equally valid alternative answers.

See Also:

• Constant Field Values

Constructor Details

ToolCallLimitExceededException

public ToolCallLimitExceededException(@Nullable String toolName,
 int limit,
 ToolExecutionResult partialToolExecutionResult)

Parameters:

toolName - the name of the tool whose per-tool limit was exceeded, or null when the total per-turn limit was exceeded instead

limit - the configured limit that was exceeded

partialToolExecutionResult - the result assembled from the tool calls already executed in the current batch, including a synthesized error response for the call that exceeded the limit

Method Details

getToolName

public @Nullable String getToolName()

The name of the tool whose per-tool limit was exceeded, or null when the total per-turn limit was exceeded instead.

getLimit

public int getLimit()

The configured limit that was exceeded.

getPartialToolExecutionResult

public ToolExecutionResult getPartialToolExecutionResult()

The result assembled from the tool calls already executed in the current batch, including a synthesized error response for the call that exceeded the limit.

buildGeneration

public Generation buildGeneration()

Builds a single Generation representing this exception, so that a limit breach is never mistaken for one of several equally valid answers.

The Generation's output is the breach message synthesized by DefaultToolCallingManager for the call that exceeded the limit. Any tool responses that completed successfully earlier in the same batch are attached under "partialToolResponses" instead of being emitted as separate, sibling generations, so completed work isn't discarded but also isn't confused with the error itself.