Exceptions

All exceptions raised by the Pinecone SDK derive from PineconeError so that a single except PineconeError block can catch every SDK error if desired.

Class Hierarchy

PineconeError
├── PineconeValueError  (also ValueError)
├── PineconeTypeError   (also TypeError)
├── PineconeConnectionError
├── PineconeTimeoutError  (also TimeoutError)
├── ResponseParsingError
├── IndexInitFailedError
└── ApiError
    ├── ConflictError (409)
    ├── NotFoundError (404)
    ├── ForbiddenError (403)
    ├── UnauthorizedError (401)
    └── ServiceError (5xx)

Base & Configuration Errors

exception pinecone.errors.exceptions.PineconeError(message)[source]

Bases: Exception

Base exception for all Pinecone SDK errors.

Parameters:

message (str)

Return type:

None

__init__(message)[source]
Parameters:

message (str)

Return type:

None

exception pinecone.errors.exceptions.PineconeValueError(message, path=None)[source]

Bases: PineconeError, ValueError

Input validation failed — invalid value.

Parameters:

  • message (str)

  • path (str | None)

Return type:

None

__init__(message, path=None)[source]
Parameters:

  • message (str)

  • path (str | None)

Return type:

None

exception pinecone.errors.exceptions.PineconeTypeError(message, path=None)[source]

Bases: PineconeError, TypeError

Input validation failed — wrong type.

Parameters:

  • message (str)

  • path (str | None)

Return type:

None

__init__(message, path=None)[source]
Parameters:

  • message (str)

  • path (str | None)

Return type:

None

exception pinecone.errors.exceptions.ResponseParsingError(message, cause=None)[source]

Bases: PineconeError

Raised when the SDK fails to parse an API response body.

Wraps the underlying deserialization error (e.g. msgspec.ValidationError) so that callers’ except PineconeError blocks always catch it.

Parameters:
Return type:

None

__init__(message, cause=None)[source]
Parameters:
Return type:

None

exception pinecone.errors.exceptions.IndexInitFailedError(index_name)[source]

Bases: PineconeError

Raised when an index fails to initialize.

Parameters:

index_name (str)

Return type:

None

__init__(index_name)[source]
Parameters:

index_name (str)

Return type:

None

Network Errors

exception pinecone.errors.exceptions.PineconeConnectionError(message)[source]

Bases: PineconeError

Raised when a network-level connection fails.

Covers DNS resolution failures, connection refused, read/write errors, and other transport-level problems.

Parameters:

message (str)

Return type:

None

exception pinecone.errors.exceptions.PineconeTimeoutError(message)[source]

Bases: PineconeError, TimeoutError

Raised when an operation exceeds its timeout.

Multiply inherits from Python’s built-in TimeoutError so that except TimeoutError blocks in caller code catch SDK timeouts without having to import a Pinecone-specific class. This is the same pattern used by PineconeValueError (extends ValueError).

Parameters:

message (str)

Return type:

None

API Errors

exception pinecone.errors.exceptions.ApiError(message, status_code, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: PineconeError

Server returned an error response.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message, status_code, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

exception pinecone.errors.exceptions.NotFoundError(message='Resource not found', status_code=404, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: ApiError

404 Not Found.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message='Resource not found', status_code=404, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

exception pinecone.errors.exceptions.ConflictError(message='Resource conflict', status_code=409, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: ApiError

409 Conflict.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message='Resource conflict', status_code=409, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

exception pinecone.errors.exceptions.UnauthorizedError(message='Invalid or missing API key', status_code=401, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: ApiError

401 Unauthorized.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message='Invalid or missing API key', status_code=401, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

exception pinecone.errors.exceptions.ForbiddenError(message='Forbidden', status_code=403, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: ApiError

403 Forbidden.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message='Forbidden', status_code=403, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

exception pinecone.errors.exceptions.ServiceError(message='Internal server error', status_code=500, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]

Bases: ApiError

5xx server error.

Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

__init__(message='Internal server error', status_code=500, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]
Parameters:

  • message (str)

  • status_code (int)

  • body (dict[str, Any] | None)

  • reason (str | None)

  • headers (dict[str, str] | None)

  • error_code (str | None)

  • request_id (str | None)

Return type:

None

Deprecated Aliases

The following names are kept for backwards compatibility and will be removed in a future major release. New code should use the canonical names listed above.

Alias

Canonical class

Notes

PineconeException

PineconeError

Legacy base-class name

PineconeApiException

ApiError

Legacy API error name

PineconeConfigurationError

PineconeValueError

Legacy configuration error

PineconeProtocolError

PineconeError

Legacy protocol error

PineconeApiTypeError

PineconeTypeError

Legacy type error

PineconeApiValueError

PineconeValueError

Legacy value error

PineconeApiAttributeError

PineconeError

Legacy attribute error

PineconeApiKeyError

PineconeError

Legacy key error

NotFoundException

NotFoundError

Legacy 404 error

UnauthorizedException

UnauthorizedError

Legacy 401 error

ForbiddenException

ForbiddenError

Legacy 403 error

ServiceException

ServiceError

Legacy 5xx error

ListConversionException

PineconeError

Legacy list conversion error

ValidationError

PineconeValueError

Legacy validation alias