# Errors

Source: `../src/openai_resptools/errors.py`

This package uses a small set of exceptions to normalize common failure modes in tool calling.

## ToolNotFoundError

Raised when a requested tool name is not present in the registry.

Common causes:
- Model called a tool name you did not register
- You passed the wrong registry instance to the runner

Where it happens:
- `ToolRegistry.get(...)`
- `ToolRunner` when resolving `call_item.name`

## ToolArgumentsError

Raised when tool arguments cannot be parsed or validated.

Common causes:
- `function_call.arguments` is invalid JSON
- JSON parses but is not an object/dict
- Pydantic validation fails for required fields or wrong types

Where it happens:
- JSON parsing and object-shape check in `../src/openai_resptools/runner.py`
- Pydantic validation in `../src/openai_resptools/tool.py`

## ToolExecutionError

Raised when the tool callable itself fails.

Notes:
- `ToolDef.call(...)` wraps any exception raised by your tool into `ToolExecutionError`.
- `ToolRunner` also has a safety net to wrap unknown exceptions raised during execution.

## RunnerMaxIterationsError

Raised when the tool-calling loop hits `max_iters` and the model keeps calling tools.

Typical mitigation:
- Increase `max_iters` for longer workflows
- Improve prompting to guide the model to stop after producing a final answer
- Ensure tool outputs are informative enough for the model to complete the task

