# exceptions
## <ApiType type="Class" slug="error" symbolName="Error" /> Error
Base exception for all Mirascope LLM errors.
**Bases:**
<TypeLink type={{"type_str": "Exception", "description": null, "kind": "simple", "symbol_name": "Exception", "doc_url": "https://docs.python.org/3/library/exceptions.html#Exception"}} />
## <ApiType type="Class" slug="provider-error" symbolName="ProviderError" /> ProviderError
Base class for errors that originate from a provider SDK.
This wraps exceptions from provider libraries (OpenAI, Anthropic, etc.)
and provides a unified interface for error handling.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
<AttributesTable
attributes={[
{
"name": "provider",
"type_info": {
"type_str": "ProviderId",
"description": null,
"kind": "simple",
"symbol_name": "ProviderId",
"doc_url": null
},
"description": "The provider that raised this error."
},
{
"name": "original_exception",
"type_info": {
"type_str": "Exception | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "Exception",
"description": null,
"kind": "simple",
"symbol_name": "Exception",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": null
}
],
"doc_url": null
},
"description": "The original exception from the provider SDK, if available."
}
]}
/>
## <ApiType type="Class" slug="a-p-i-error" symbolName="APIError" /> APIError
Base class for HTTP-level API errors.
**Bases:**
<TypeLink type={{"type_str": "ProviderError", "description": null, "kind": "simple", "symbol_name": "ProviderError", "doc_url": "/docs/api/llm/exceptions#provider-error"}} />
<AttributesTable
attributes={[
{
"name": "status_code",
"type_info": {
"type_str": "int | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "int",
"description": null,
"kind": "simple",
"symbol_name": "int",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": null
}
],
"doc_url": null
},
"description": "The HTTP status code, if available."
}
]}
/>
## <ApiType type="Class" slug="authentication-error" symbolName="AuthenticationError" /> AuthenticationError
Raised for authentication failures (401, invalid API keys).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="permission-error" symbolName="PermissionError" /> PermissionError
Raised for permission/authorization failures (403).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="bad-request-error" symbolName="BadRequestError" /> BadRequestError
Raised for malformed requests (400, 422).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="not-found-error" symbolName="NotFoundError" /> NotFoundError
Raised when requested resource is not found (404).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="rate-limit-error" symbolName="RateLimitError" /> RateLimitError
Raised when rate limits are exceeded (429).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="server-error" symbolName="ServerError" /> ServerError
Raised for server-side errors (500+).
**Bases:**
<TypeLink type={{"type_str": "APIError", "description": null, "kind": "simple", "symbol_name": "APIError", "doc_url": "/docs/api/llm/exceptions#a-p-i-error"}} />
## <ApiType type="Class" slug="connection-error" symbolName="ConnectionError" /> ConnectionError
Raised when unable to connect to the API (network issues, timeouts).
**Bases:**
<TypeLink type={{"type_str": "ProviderError", "description": null, "kind": "simple", "symbol_name": "ProviderError", "doc_url": "/docs/api/llm/exceptions#provider-error"}} />
## <ApiType type="Class" slug="timeout-error" symbolName="TimeoutError" /> TimeoutError
Raised when requests timeout or deadline exceeded.
**Bases:**
<TypeLink type={{"type_str": "ProviderError", "description": null, "kind": "simple", "symbol_name": "ProviderError", "doc_url": "/docs/api/llm/exceptions#provider-error"}} />
## <ApiType type="Class" slug="response-validation-error" symbolName="ResponseValidationError" /> ResponseValidationError
Raised when API response fails validation.
This wraps the APIResponseValidationErrors that OpenAI and Anthropic both return.
**Bases:**
<TypeLink type={{"type_str": "ProviderError", "description": null, "kind": "simple", "symbol_name": "ProviderError", "doc_url": "/docs/api/llm/exceptions#provider-error"}} />
## <ApiType type="Class" slug="tool-error" symbolName="ToolError" /> ToolError
Base class for errors that occur during tool execution.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
## <ApiType type="Class" slug="tool-execution-error" symbolName="ToolExecutionError" /> ToolExecutionError
Raised if an uncaught exception is thrown while executing a tool.
**Bases:**
<TypeLink type={{"type_str": "ToolError", "description": null, "kind": "simple", "symbol_name": "ToolError", "doc_url": "/docs/api/llm/exceptions#tool-error"}} />
<AttributesTable
attributes={[
{
"name": "tool_exception",
"type_info": {
"type_str": "Exception",
"description": null,
"kind": "simple",
"symbol_name": "Exception",
"doc_url": null
},
"description": "The exception that was thrown while executing the tool."
}
]}
/>
## <ApiType type="Class" slug="tool-not-found-error" symbolName="ToolNotFoundError" /> ToolNotFoundError
Raised if a tool call does not match any registered tool.
**Bases:**
<TypeLink type={{"type_str": "ToolError", "description": null, "kind": "simple", "symbol_name": "ToolError", "doc_url": "/docs/api/llm/exceptions#tool-error"}} />
<AttributesTable
attributes={[
{
"name": "tool_name",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
"description": "The name of the tool that was not found."
}
]}
/>
## <ApiType type="Class" slug="parse-error" symbolName="ParseError" /> ParseError
Raised when response.parse() fails to parse the response content.
This wraps errors from JSON extraction, JSON parsing, Pydantic validation,
or custom OutputParser functions.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
<AttributesTable
attributes={[
{
"name": "original_exception",
"type_info": {
"type_str": "Exception",
"description": null,
"kind": "simple",
"symbol_name": "Exception",
"doc_url": null
},
"description": "The original exception that caused the parse failure."
}
]}
/>
## <ApiType type="Function" slug="mirascope-llm-exceptions--parse-error-retry_message" symbolName="retry_message" /> retry_message
Generate a message suitable for retrying with the LLM.
Returns a user-friendly message describing what went wrong,
suitable for including in a retry prompt.
<ParametersTable
parameters={[
{
"name": "self",
"type_info": {
"type_str": "Any",
"description": null,
"kind": "simple",
"symbol_name": null,
"doc_url": null
}
}
]}
/>
<ReturnTable
returnType={{
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": "https://docs.python.org/3/library/stdtypes.html#str"
}
}}
/>
## <ApiType type="Class" slug="feature-not-supported-error" symbolName="FeatureNotSupportedError" /> FeatureNotSupportedError
Raised if a Mirascope feature is unsupported by chosen provider.
If compatibility is model-specific, then `model_id` should be specified.
If the feature is not supported by the provider at all, then it may be `None`.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
<AttributesTable
attributes={[
{
"name": "provider_id",
"type_info": {
"type_str": "ProviderId",
"description": null,
"kind": "simple",
"symbol_name": "ProviderId",
"doc_url": null
}
},
{
"name": "model_id",
"type_info": {
"type_str": "ModelId | None",
"description": null,
"kind": "union",
"base_type": {
"type_str": "Union",
"description": null,
"kind": "simple",
"symbol_name": "Union",
"doc_url": null
},
"parameters": [
{
"type_str": "ModelId",
"description": null,
"kind": "simple",
"symbol_name": "ModelId",
"doc_url": null
},
{
"type_str": "None",
"description": null,
"kind": "simple",
"symbol_name": "None",
"doc_url": null
}
],
"doc_url": null
}
},
{
"name": "feature",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
}
}
]}
/>
## <ApiType type="Class" slug="no-registered-provider-error" symbolName="NoRegisteredProviderError" /> NoRegisteredProviderError
Raised when no provider is registered for a given model_id.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
<AttributesTable
attributes={[
{
"name": "model_id",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
}
}
]}
/>
## <ApiType type="Class" slug="missing-a-p-i-key-error" symbolName="MissingAPIKeyError" /> MissingAPIKeyError
Raised when no API key is available for a provider.
This error is raised during auto-registration when the required API key
environment variable is not set. If a Mirascope fallback is available,
the error message will suggest using MIRASCOPE_API_KEY as an alternative.
**Bases:**
<TypeLink type={{"type_str": "Error", "description": null, "kind": "simple", "symbol_name": "Error", "doc_url": "/docs/api/llm/exceptions#error"}} />
<AttributesTable
attributes={[
{
"name": "provider_id",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
"description": "The provider that requires an API key."
},
{
"name": "env_var",
"type_info": {
"type_str": "str",
"description": null,
"kind": "simple",
"symbol_name": "str",
"doc_url": null
},
"description": "The environment variable that should contain the API key."
}
]}
/>