Exceptions
==========

Exception hierarchy for error handling in the Pinecone SDK.

Exception Hierarchy
-------------------

All Pinecone exceptions inherit from :class:`~pinecone.PineconeError`:

.. code-block:: text

   PineconeError
   ├── ConfigurationError
   │   ├── InvalidAPIKeyError
   │   └── InvalidConfigError
   ├── APIConnectionError
   │   ├── TimeoutError
   │   └── ConnectionError
   └── APIError
       ├── BadRequestError
       ├── UnauthorizedError
       ├── ForbiddenError
       ├── NotFoundError
       ├── RateLimitError
       └── ServerError

Base Exception
--------------

.. autoclass:: pinecone.PineconeError
   :members:
   :show-inheritance:

Configuration Errors
--------------------

.. autoclass:: pinecone.ConfigurationError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.InvalidAPIKeyError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.InvalidConfigError
   :members:
   :show-inheritance:

Connection Errors
-----------------

.. autoclass:: pinecone.APIConnectionError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.TimeoutError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.ConnectionError
   :members:
   :show-inheritance:

API Errors
----------

.. autoclass:: pinecone.APIError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.BadRequestError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.UnauthorizedError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.ForbiddenError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.NotFoundError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.RateLimitError
   :members:
   :show-inheritance:

.. autoclass:: pinecone.ServerError
   :members:
   :show-inheritance:

Error Handling Examples
-----------------------

Basic error handling:

.. code-block:: python

   from pinecone import Pinecone, PineconeError, APIError

   pc = Pinecone(api_key="your-api-key")

   try:
       response = pc.inference.embed(
           model="multilingual-e5-large",
           texts=["Hello world"]
       )
   except APIError as e:
       print(f"API error: {e}")
   except PineconeError as e:
       print(f"Pinecone error: {e}")

Handling specific errors:

.. code-block:: python

   from pinecone import (
       Pinecone,
       UnauthorizedError,
       RateLimitError,
       NotFoundError
   )

   pc = Pinecone(api_key="your-api-key")

   try:
       response = pc.inference.embed(
           model="multilingual-e5-large",
           texts=["Hello world"]
       )
   except UnauthorizedError:
       print("Invalid API key")
   except RateLimitError:
       print("Rate limit exceeded, retry later")
   except NotFoundError:
       print("Model not found")
