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 class for every exception the SDK raises.

Catch this when one handler should cover any SDK failure; catch a subclass when a particular failure needs its own recovery. message holds the text the SDK or the server produced.

Three subclasses also derive from a builtin — PineconeValueError from ValueError, PineconeTypeError from TypeError, PineconeTimeoutError from TimeoutError — so an except ValueError already in your code catches those without importing anything from Pinecone.

Examples

>>> from pinecone import NotFoundError, PineconeError
>>> try:
...     raise NotFoundError(message="No index named 'movie-recommendations'")
... except PineconeError as exc:
...     print(type(exc).__name__, exc.message)
NotFoundError No index named 'movie-recommendations'

See also

Error Handling — which errors a given call produces, what the SDK retries before raising, and how to order handlers.

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

An argument had the right type but an unusable value.

The SDK’s own validation raises this before the request goes out, so nothing was created or changed. Fix the argument the message names.

path locates the offending field when the raiser supplied one, and str(exc) then prefixes the message with at <path>:. Also derives from ValueError, so an except ValueError already in your code catches it.

Examples

>>> from pinecone import PineconeValueError
>>> print(PineconeValueError("dimension must be positive", "fields.embedding"))
at fields.embedding: dimension must be positive

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

An argument was of a type the SDK cannot use.

Raised before the request goes out, so nothing was created or changed. Passing a keyword this SDK version no longer accepts produces this too, with a message naming the current argument to use instead.

When the failure is a value inside a request body that will not JSON-encode, path locates it — records[2].embedding — which is the part worth reading on a bulk call. str(exc) prefixes the message with at <path>:. Also derives from TypeError.

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

The response arrived but the SDK could not decode it.

The request succeeded, so this is not a failure you can fix by changing it. The usual cause is a response carrying a shape this SDK version does not model — a new deployment type or read-capacity mode, for instance — which an SDK upgrade resolves.

cause holds the underlying deserialization error, and str(exc) appends it, so the message already names the field that would not decode. Wrapping it this way is what lets an except PineconeError block catch a decode failure at all.

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

An index entered InitializationFailed while the SDK waited for it.

Only a call that polls for readiness raises this — create() and create_for_model() do so unless you pass timeout=-1 to return immediately. The index exists but will never become ready: delete it and create again, changing the deployment if that is what failed. index_name is the index that failed.

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

An index reached a terminal state while the SDK waited for it.

The terminal states are Terminating and Disabled. Something outside this call deleted or disabled the index mid-wait, so waiting longer cannot succeed. name and state say which index and which state; describe() confirms whether it still exists.

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

The connection failed before any response arrived.

Covers DNS resolution failures, connection refused, read/write errors, and other transport-level problems. The SDK retries transport failures, so one reaching your code means the retry budget was spent — look at DNS, egress rules, and any proxy between you and Pinecone rather than at the request.

Parameters:: message (str)
Return type:: None

exception pinecone.errors.exceptions.PineconeTimeoutError(message, *, response=None)[source]¶

Bases: PineconeError, TimeoutError

An operation exceeded its timeout.

Two deadlines produce this: a single HTTP request that outran the client’s request timeout, and a readiness wait — creating or deleting an index, say — that outran the timeout you passed. The first is worth retrying; the second usually means the resource is still working, so describe it rather than re-issuing the call.

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

The server answered with an HTTP error status.

Every status-specific class below derives from this one, so except ApiError catches all of them. A status with no dedicated subclass reaches the caller as a bare ApiError — 400 and 422, which are what a request the server considers malformed produces.

Two attributes are worth reading. status_code says which class of failure it was; body is the parsed JSON response, and it is where a field-level explanation lives when the server sent one. str(exc) already renders the status, the server’s error code, and the request id, so logging the exception loses nothing. Quote request_id when you open a support ticket.

Examples

>>> from pinecone import ApiError
>>> exc = ApiError(
...     "No index named 'movie-recommendations'",
...     404,
...     body={"error": {"code": "NOT_FOUND"}},
...     request_id="req-9f2c",
... )
>>> print(exc)
[404] No index named 'movie-recommendations' (request_id: req-9f2c)
>>> exc.status_code, exc.body["error"]["code"]
(404, 'NOT_FOUND')

See also

Error Handling — the full attribute table, and the handler shape for each status.

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 — the resource the request named does not exist.

A misspelled name, a resource someone else already deleted, or an API key scoped to a different project than the one that owns the resource all produce this. When you only want to know whether an index is there, exists() is clearer than catching this.

Note

A 404 is not proof of absence everywhere. describe() answers 404 for any failure to read the restore-job store, so there it means “could not produce this job”, not “no such job” — do not key control flow on it.

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 — the request conflicts with the resource’s current state.

Creating an index, collection, or backup under a name that is already taken is the common case. Guard the create with exists(), or catch this and treat it as a no-op when concurrent callers make the check pointless.

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 — the request carried no usable credential.

The API key was missing, malformed, or has been deleted, or an Admin client’s OAuth2 credentials were rejected. Nothing about the request itself will fix it and retrying will not help: supply a valid credential. Check PINECONE_API_KEY first when you did not pass api_key explicitly.

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 — the credential is valid but the operation is not permitted.

Three causes account for most of these: the key’s roles do not cover the operation, a quota on the project or organization has been reached, or a protection setting on the resource forbids it — deletion protection makes delete() answer 403 until you turn it off with configure().

Retrying never helps. message carries the server’s explanation, which is what distinguishes the three.

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 — the organization’s billing state blocks the operation.

Raised where the control plane gates resource creation on payment, notably create() and create(), which need the organization to have an active payment method or a plan that permits the request.

Retrying will not help: you 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 — the target resource is not in a state that permits the request.

The request was well-formed. 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 — the request was throttled.

The SDK retries 429 on its own, so one reaching your code means the retry budget was already spent. Retrying immediately in a loop will not get through; reduce the request rate, or raise the retry allowance.

retry_after is how long the server asked you to wait, in seconds. It is parsed from the Retry-After response header when that header is present and expressible as a non-negative number of seconds; an HTTP-date value is not parsed, and leaves retry_after as None.

See also

Retries and Resilience — what the SDK retries by default and how to change it.

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 — the server failed to handle a well-formed request.

Nothing about the request needs changing. The SDK already retries the common 5xx statuses, so one reaching your code means the retry budget was spent — back off further before trying again. A 5xx outside the retryable set arrives on the first attempt instead.

Read status_code to tell the two apart, and quote request_id if the failure persists.

See also

Retries and Resilience — which statuses are retried by default.

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 ¶