# Error Handling

All exceptions raised by the SDK are subclasses of `PineconeError`, so a single
`except PineconeError` block catches everything the SDK can raise. More specific
subclasses let you handle individual failure modes differently.

## Exception Hierarchy

```
PineconeError (base)
├── ApiError                    # Server returned an HTTP error response
│   ├── NotFoundError           # 404
│   ├── ConflictError           # 409
│   ├── UnauthorizedError       # 401
│   ├── ForbiddenError          # 403
│   └── ServiceError            # 5xx
├── PineconeConnectionError     # Network-level failure (DNS, refused, transport)
├── PineconeTimeoutError        # Operation exceeded its timeout
├── PineconeValueError          # Invalid value passed to the SDK
└── PineconeTypeError           # Wrong type passed to the SDK
```

Full reference: {doc}`/reference/exceptions`.

## Catching Specific Errors

```python
from pinecone import Pinecone
from pinecone.errors import (
    NotFoundError,
    ConflictError,
    UnauthorizedError,
    ForbiddenError,
    ServiceError,
    PineconeConnectionError,
    PineconeTimeoutError,
)

pc = Pinecone()

try:
    pc.indexes.delete("nonexistent-index")
except NotFoundError:
    print("Index does not exist")
except ConflictError:
    print("Operation conflicts with current state")
except UnauthorizedError:
    print("Invalid or missing API key")
except ForbiddenError:
    print("API key lacks permission for this operation")
except ServiceError as exc:
    print(f"Server error {exc.status_code}: {exc.message}")
except PineconeConnectionError:
    print("Network error — check your connection")
except PineconeTimeoutError:
    print("Request timed out")
```

## ApiError Attributes

`ApiError` (and its subclasses) carry structured context:

| Attribute | Type | Description |
|-----------|------|-------------|
| `status_code` | `int` | HTTP status code returned by the server |
| `message` | `str` | Human-readable error description |
| `body` | `dict \| None` | Parsed response body, if available |
| `reason` | `str \| None` | HTTP reason phrase |
| `headers` | `dict \| None` | Response headers |

```python
from pinecone.errors import ApiError

try:
    pc.indexes.describe("my-index")
except ApiError as exc:
    print(exc.status_code)  # e.g. 404
    print(exc.message)
    if exc.body:
        print(exc.body.get("error", {}).get("message"))
```

## ConflictError when creating an index

If you call `pc.indexes.create()` and an index with that name already exists, the server
returns a 409 and the SDK raises `ConflictError`.  The idiomatic fix is to guard the
create call with `pc.indexes.exists()`:

```python
from pinecone import Pinecone

pc = Pinecone()

if not pc.indexes.exists("my-index"):
    pc.indexes.create(
        name="my-index",
        spec={"serverless": {"cloud": "aws", "region": "us-east-1"}},
        dimension=1536,
        metric="cosine",
    )
```

`exists()` returns `True` if an index with that name is present, `False` otherwise.

If you genuinely cannot check first (e.g. concurrent callers), catch `ConflictError`
and treat it as a no-op:

```python
from pinecone import Pinecone
from pinecone.errors import ConflictError

pc = Pinecone()

try:
    pc.indexes.create(
        name="my-index",
        spec={"serverless": {"cloud": "aws", "region": "us-east-1"}},
        dimension=1536,
        metric="cosine",
    )
except ConflictError:
    pass  # index already exists, nothing to do
```

## Retries

The SDK retries failed requests automatically. The default `RetryConfig` retries up to
**3 attempts total** (1 initial + 2 retries) with exponential backoff for status codes
`429`, `500`, `502`, `503`, and `504`.

Customize retry behavior by passing a `RetryConfig` to `Pinecone()`:

```python
from pinecone import Pinecone, RetryConfig

pc = Pinecone(
    retry_config=RetryConfig(
        max_retries=5,
        backoff_factor=1.0,
        max_wait=30.0,
        retryable_status_codes=frozenset({429, 500, 503}),
    )
)
```

To disable retries entirely, set `max_retries=1`:

```python
pc = Pinecone(retry_config=RetryConfig(max_retries=1))
```

## Timeouts

The default request timeout is **30 seconds**. Pass `timeout` to the `Pinecone`
constructor to change the client-wide default:

```python
pc = Pinecone(timeout=10.0)
```

Many methods also accept a per-request `timeout` keyword argument that overrides the
client default for that call:

```python
# Wait up to 60 seconds for this specific upsert
index.upsert(vectors=[...], timeout=60.0)
```

When a request times out, the SDK raises `PineconeTimeoutError`, which also inherits
from Python's built-in `TimeoutError`:

```python
except TimeoutError:
    # Catches PineconeTimeoutError as well
    ...
```