Error handling

This page covers how to read Pinecone API errors, catch them in your code, retry the ones that are transient, and stay within rate limits.

Understand error types

Pinecone uses conventional HTTP response codes to indicate the success or failure of API requests:

2xx codes indicate success
4xx codes indicate client errors (issues with your request)
5xx codes indicate server errors (issues with Pinecone’s servers)

Client errors (4xx)

Client errors indicate problems with your request. These errors typically require changes to your code or configuration:

400 - Invalid Argument: Your request contains invalid parameters. Check your request format and parameters.
401 - Unauthenticated: Your API key is missing or invalid. Verify your API key.
402 - Payment Required: Your account has a payment issue or may be deactivated for non-payment. Check your billing status in the console and see Account deactivation for non-payment.
403 - Forbidden: You’ve exceeded a quota or hit deletion protection.
404 - Not Found: The requested resource doesn’t exist. Verify the resource name and that it hasn’t been deleted.
409 - Already Exists: You’re trying to create a resource that already exists.
429 - Too Many Requests: You’re being rate-limited. Implement backoff and retry logic.

Server errors (5xx)

Server errors indicate temporary issues with Pinecone’s infrastructure:

500 - Unknown: An internal server error occurred.
502 - Bad Gateway: The API gateway received an invalid response from a backend service.
503 - Unavailable: The service is currently unavailable.
504 - Gateway Timeout: The API gateway didn’t receive a timely response from the backend server. This can occur due to slow requests or backend processing delays.

These errors are usually transient, so retry them with exponential backoff.

Capture errors

Python SDK

The Python SDK raises exceptions that you can catch and handle:

Python

from pinecone import Pinecone
from pinecone.exceptions import PineconeException

pc = Pinecone(api_key="YOUR_API_KEY")

# To get the unique host for an index,
# see https://docs.pinecone.io/guides/indexes/target-an-index
index = pc.index(host="INDEX_HOST")

try:
    index.documents.upsert(
        namespace="articles",
        documents=[
            {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."}
        ],
    )
except PineconeException as e:
    # Handle Pinecone-specific errors
    print(f"Pinecone error: {e}")
except Exception as e:
    # Handle other errors
    print(f"Unexpected error: {e}")

See the Python SDK documentation for more details on exception handling.

Node.js SDK

The Node.js SDK uses standard JavaScript error handling:

JavaScript

import { Pinecone } from '@pinecone-database/pinecone';

const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });

try {
  // To get the unique host for an index,
  // see https://docs.pinecone.io/guides/indexes/target-an-index
  const index = pc.index({ host: 'INDEX_HOST', namespace: 'articles' });
  await index.documents.upsert({
    documents: [
      { _id: 'doc1', body: 'Pinecone serverless indexes scale automatically with your workload.' },
    ],
  });
} catch (error) {
  console.error('Error upserting data:', error);
  // Handle the error appropriately
}

See the Node.js SDK documentation for more information.

Other SDKs

For error handling in other languages, see the documentation for your SDK:

Implement retry logic

For transient errors (5xx codes and 429 rate limiting), implement retry logic. Start with basic retries for simple use cases, or use exponential backoff for production systems.

Basic retry logic

For simple use cases, start with a basic retry loop with fixed delays:

Python

import time
from pinecone.exceptions import PineconeException

def simple_retry(func, max_retries=3, delay=2):
    """
    Retry a function with a fixed delay between attempts.

    Args:
        func: Function to retry
        max_retries: Maximum number of retry attempts
        delay: Delay in seconds between retries
    """
    for attempt in range(max_retries):
        try:
            return func()
        except PineconeException as e:
            # Retries every Pinecone error. For status-aware retries, see Exponential backoff.
            if attempt == max_retries - 1:
                raise  # Last attempt, re-raise the exception

            print(f"Attempt {attempt + 1} failed, retrying in {delay}s...")
            time.sleep(delay)

# Usage
# `index` is an index connection. See https://docs.pinecone.io/guides/indexes/target-an-index
documents = [
    {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."}
]

try:
    simple_retry(lambda: index.documents.upsert(namespace="articles", documents=documents))
except Exception as e:
    print(f"Failed after retries: {e}")

This basic approach works well for occasional transient errors, but for production systems with higher traffic, use exponential backoff instead.

Exponential backoff

Exponential backoff progressively increases the wait time between retries to avoid overwhelming the service:

Python

import time
import random
from pinecone.exceptions import PineconeException

def exponential_backoff_retry(func, max_retries=5, base_delay=1, max_delay=60):
    """
    Retry a function with exponential backoff.

    Args:
        func: Function to retry
        max_retries: Maximum number of retry attempts
        base_delay: Initial delay in seconds
        max_delay: Maximum delay between retries
    """
    for attempt in range(max_retries):
        try:
            return func()
        except PineconeException as e:
            if attempt == max_retries - 1:
                raise  # Last attempt, re-raise the exception

            # Get status code if available
            status_code = getattr(e, 'status_code', None)

            # Only retry on 5xx errors or 429 (rate limiting)
            if status_code and (status_code >= 500 or status_code == 429):
                # Calculate delay with exponential backoff and jitter
                delay = min(base_delay * (2 ** attempt), max_delay)
                jitter = random.uniform(0, delay * 0.1)  # Add 10% jitter
                wait_time = delay + jitter

                print(f"Retry attempt {attempt + 1}/{max_retries} after {wait_time:.2f}s")
                time.sleep(wait_time)
            else:
                # Don't retry client errors (4xx except 429)
                raise

# Usage
# `index` is an index connection. See https://docs.pinecone.io/guides/indexes/target-an-index
documents = [
    {"_id": "doc1", "body": "Pinecone serverless indexes scale automatically with your workload."}
]

try:
    exponential_backoff_retry(lambda: index.documents.upsert(namespace="articles", documents=documents))
except Exception as e:
    print(f"Failed after retries: {e}")

Built-in retries in the Go SDK

The Go SDK has built-in retries with exponential backoff. Set a RetryPolicy on the client and it applies to both the REST (control/data/inference) and gRPC (data plane) clients. Over REST, the SDK retries 429 on every request, but it retries 5xx and transport errors only for idempotent methods such as GET, PUT, and DELETE, so it doesn’t replay a request that might have already changed data. Documents API calls use POST, so they aren’t retried on 5xx. To retry them, wrap them in your own retry loop, like the Python examples above. Searches are safe to retry, and so are upserts, because an upsert by _id replaces the whole document. The gRPC client also retries UNAVAILABLE and RESOURCE_EXHAUSTED. Other 4xx errors are never retried.

package main

import (
	"os"

	"github.com/pinecone-io/go-pinecone/v7/pinecone"
)

func main() {
	pc, err := pinecone.NewClient(pinecone.NewClientParams{
		ApiKey:      os.Getenv("PINECONE_API_KEY"),
		RetryPolicy: pinecone.DefaultRetryPolicy(), // 3 retries, 500ms base, 30s cap, 2x backoff
	})
	if err != nil {
		panic(err)
	}
	_ = pc
}

To customize the behavior, construct a RetryPolicy with your own MaxRetries, BaseDelay, MaxDelay, and BackoffMultiplier. See the Go SDK documentation for details.

Retry best practices

Add jitter: Random variation in retry timing keeps many clients from retrying at the same moment.
Set max retries: Prevent infinite retry loops.
Cap delay time: Don’t wait indefinitely between retries.
Don’t retry client errors: 4xx errors (except 429) won’t resolve with retries.
Log retry attempts: Track retry behavior for monitoring and debugging.

Handle rate limits (429)

When you receive a 429 error, you’re being rate-limited. See Rate limits for current limits. Rate limits protect your applications and the health of the serverless infrastructure. Most limits can be raised on request. If you need higher limits to scale, contact Support with details about your use case.

Indexes built on Dedicated Read Nodes aren’t subject to read unit limits for query, fetch, list, and full-text search operations. For sizing and capacity planning guidance, see the Dedicated Read Nodes guide.

Best practices

Retry with exponential backoff.
Proactively monitor request metrics and reduce the request rate if you’re approaching limits.
Use batching to reduce the number of requests.
For high-throughput needs, see Increase throughput.

Get support

If you’ve implemented error handling and retry logic but still see errors:

Review Get help for how to file a ticket that gets a fast resolution.
Gather the following information:
- Index name and project name
- Error messages and stack traces
- Timestamp of errors
- Request and response examples (without sensitive data)
- Whether the issue is reproducible
Contact Support.

Ensure your plan tier provides the support SLA you need for production workloads.

Get started

Indexes

Data

Search

Optimize

Cost

Production

Agents

Legacy

Understand error types

Client errors (4xx)

Server errors (5xx)

Capture errors

Python SDK

Node.js SDK

Other SDKs

Implement retry logic

Basic retry logic

Exponential backoff

Built-in retries in the Go SDK

Retry best practices

Handle rate limits (429)

Best practices

Get support

​Understand error types

​Client errors (4xx)

​Server errors (5xx)

​Capture errors

​Python SDK

​Node.js SDK

​Other SDKs

​Implement retry logic

​Basic retry logic

​Exponential backoff

​Built-in retries in the Go SDK

​Retry best practices

​Handle rate limits (429)

​Best practices

​Get support

Understand error types

Client errors (4xx)

Server errors (5xx)

Capture errors

Python SDK

Node.js SDK

Other SDKs

Implement retry logic

Basic retry logic

Exponential backoff

Built-in retries in the Go SDK

Retry best practices

Handle rate limits (429)

Best practices

Get support