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
├── IndexTerminatedError
└── ApiError
    ├── ConflictError (409)
    ├── NotFoundError (404)
    ├── ForbiddenError (403)
    ├── UnauthorizedError (401)
    ├── PaymentRequiredError (402)
    ├── FailedPreconditionError (412)
    ├── RateLimitError (429)
    └── 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:

message (str)
cause (Exception | None)

Return type:

None

__init__(message, cause=None)[source]¶

Parameters:

message (str)
cause (Exception | None)

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

exception pinecone.errors.exceptions.IndexTerminatedError(name, state)[source]¶

Bases: PineconeError

Raised when polling an index that has entered a terminal non-init state.

Terminal states include Terminating and Disabled.

Parameters:

name (str)
state (str)

Return type:

None

__init__(name, state)[source]¶

Parameters:

name (str)
state (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, *, response=None)[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) – Description of what timed out.
response (Any | None) – Partial result, when the timeout interrupted a bulk operation that had already applied some of its work. Carrying it means the caller can tell what landed instead of having to re-send everything; response.failed_items is what remains. None for timeouts with nothing partial to report.

Return type:

None

__init__(message, *, response=None)[source]¶

Parameters:

message (str)
response (Any | None)

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.PaymentRequiredError(message='Payment required', status_code=402, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]¶

Bases: ApiError

402 Payment Required.

The organization’s billing state blocks the operation. Raised where the control plane gates resource creation on payment — notably admin.projects.create and admin.api_keys.create, which require the organization to have an active payment method or a plan that permits the request.

Retrying will not help: the caller (or an organization owner) has to resolve the billing state first. message carries the server’s explanation verbatim, so it is the authoritative description of what needs fixing.

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='Payment required', status_code=402, 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.FailedPreconditionError(message='Precondition failed', status_code=412, body=None, *, reason=None, headers=None, error_code=None, request_id=None)[source]¶

Bases: ApiError

412 Precondition Failed.

The request was well-formed but the target resource is not in a state that permits it. This is the dominant admin failure class: deleting a project or organization that still owns resources, or deleting a backup with a restore job still in flight, all answer 412.

The precondition is usually satisfiable — delete the blocking resources, or wait for the in-flight operation to finish, then retry. message carries the server’s explanation verbatim and typically names the specific resources or job ids that are in the way.

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='Precondition failed', status_code=412, 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.RateLimitError(message='Rate limit exceeded', status_code=429, body=None, *, reason=None, headers=None, error_code=None, request_id=None, retry_after=None)[source]¶

Bases: ApiError

429 Too Many Requests.

retry_after is parsed from the Retry-After response header when present and expressible as a non-negative number of seconds. HTTP-date values are not parsed and result in retry_after = None.

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)
retry_after (float | None)

Return type:

None

__init__(message='Rate limit exceeded', status_code=429, body=None, *, reason=None, headers=None, error_code=None, request_id=None, retry_after=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)
retry_after (float | 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
`RateLimitException`	`RateLimitError`	Legacy 429 error
`ListConversionException`	`PineconeError`	Legacy list conversion error
`ValidationError`	`PineconeValueError`	Legacy validation alias

Exceptions¶

Class Hierarchy¶

Base & Configuration Errors¶

Network Errors¶

API Errors¶

Deprecated Aliases¶

Class Hierarchy ¶

Base & Configuration Errors ¶

Network Errors ¶

API Errors ¶

Deprecated Aliases ¶