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. Check your billing status in the console.
- 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.
- 503 - Unavailable: The service is temporarily unavailable.
Capture errors
Each SDK provides error handling mechanisms specific to the language:Python SDK
The Python SDK raises exceptions that you can catch and handle:Node.js SDK
The Node.js SDK uses standard JavaScript error handling:Other SDKs
For SDK-specific error handling patterns, see the documentation for your language: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:Exponential backoff
Exponential backoff progressively increases the wait time between retries to avoid overwhelming the service:Key retry principles
- Add jitter: Random variation in retry timing helps avoid thundering herd problems.
- 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 help protect your applications and maintain the health of the serverless infrastructure. Most limits can be adjusted upon request—if you need higher limits to scale, contact Support with details about your use case. Best practices:- Implement exponential backoff as described above.
- 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.
Getting support
If you’ve implemented error handling and retry logic but continue to experience issues:- Review How to work with Support for best practices.
- Gather the following information:
- Index name and project name
- Error messages and stack traces
- Timestamp of errors
- Request/response examples (without sensitive data)
- Whether the issue is reproducible
- Contact Support.