Postconditions: what we check

• upsert · upsert-no-error-handling

  error
  Whenindex.upsert() called without try-catch or .catch() handler
  ThrowsPineconeApiError (non-2xx responses: 401 auth, 400 bad request, 429 rate limit, 5xx server error). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). Error on malformed input.
  Required handlingCaller MUST wrap await index.upsert() in try-catch. Failure to catch means vectors are silently not stored — RAG pipelines degrade with no feedback. Check error type: auth errors need config fix, rate limit needs retry with backoff, 5xx needs retry or circuit breaker. try { await index.upsert([{ id: 'doc-1', values: embedding }]); } catch (error) { console.error('Failed to upsert vectors:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• query · query-no-error-handling

  error
  Whenindex.query() called without try-catch or .catch() handler
  ThrowsPineconeApiError (401 auth, 400 bad namespace, 429 rate limit, 5xx). PineconeConnectionError (network failure). Error on mismatched vector dimension (query vector dimension must match index dimension).
  Required handlingCaller MUST wrap await index.query() in try-catch. Uncaught error in query path causes unhandled rejection — API routes return 500, RAG answers become unavailable. Log the error and return a safe fallback (empty results, cached response, or error to user). try { const results = await index.query({ vector: queryEmbedding, topK: 10, includeMetadata: true, }); return results.matches; } catch (error) { console.error('Pinecone query failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][4]
• deleteOne · deleteone-no-error-handling

  error
  Whenindex.deleteOne() called without try-catch or .catch() handler
  ThrowsPineconeApiError (401 auth, 404 namespace not found, 429 rate limit, 5xx). PineconeConnectionError (network failure).
  Required handlingCaller MUST wrap await index.deleteOne() in try-catch. Silent delete failures leave stale vectors in the index, causing incorrect semantic search results and privacy/consistency issues.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• deleteMany · deletemany-no-error-handling

  error
  Whenindex.deleteMany() called without try-catch or .catch() handler
  ThrowsPineconeApiError (401 auth, 400 invalid filter, 429 rate limit, 5xx). PineconeConnectionError (network failure).
  Required handlingCaller MUST wrap await index.deleteMany() in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6]
• fetch · fetch-no-error-handling

  error
  Whenindex.fetch() called without try-catch or .catch() handler
  ThrowsPineconeApiError (401 auth, 429 rate limit, 5xx server error). PineconeConnectionError (network failure).
  Required handlingCaller MUST wrap await index.fetch() in try-catch.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7]
• listIndexes · listindexes-no-error-handling

  error
  Whenpinecone.listIndexes() called without try-catch or .catch() handler
  ThrowsPineconeApiError (401 invalid API key, 429 rate limit, 5xx). PineconeConnectionError (network failure).
  Required handlingCaller MUST wrap await pinecone.listIndexes() in try-catch. Failure during index listing (e.g., in admin routes or startup checks) causes the caller to crash with an unhandled rejection.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[8]
• update · update-no-error-handling

  error
  Whenindex.update() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid params, or HTTP 403 — quota exceeded). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.update() in try-catch. Network and auth failures throw — metadata pipelines that update records fail silently if exceptions are swallowed. try { await index.update({ id: 'doc-1', metadata: { status: 'processed' } }); } catch (error) { console.error('Pinecone update failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[9][10][11]
• update · update-silent-missing-id

  warning
  Whenindex.update() called with an id that does not exist in the index, and the caller assumes a returned success means the record was updated.
  ThrowsDoes NOT throw. Returns HTTP 200 (success) even when no record matched the provided ID. The Pinecone API silently ignores updates to non-existent records per documented behavior.
  Required handlingCallers that require confirmation of the update MUST call index.fetch({ ids: [id] }) after the update to verify the record exists and contains the updated values. Do not assume update success implies the record exists. // Pattern: verify update actually landed await index.update({ id: recordId, metadata: newMeta }); const verify = await index.fetch({ ids: [recordId] }); if (!verify.records[recordId]) { throw new Error(`Record ${recordId} not found — update had no effect`); }
  costmediumin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[9]
• createIndex · createindex-no-error-handling

  error
  Whenpinecone.createIndex() called without try-catch or .catch() handler
  ThrowsPineconeBadRequestError (HTTP 400 — invalid params: bad metric, invalid name; or HTTP 403 — project quota exceeded, "Increase your quota or upgrade"). PineconeConflictError (HTTP 409 — index name already exists in project). PineconeNotFoundError (HTTP 404 — invalid cloud/region combination for serverless). PineconeConnectionError (network failures). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await pinecone.createIndex() in try-catch. Quota errors (PineconeBadRequestError with 403 body) require account upgrade. Conflict errors (PineconeConflictError) are often handled by using suppressConflicts: true option, which skips creation when index exists. try { await pinecone.createIndex({ name: 'my-index', dimension: 1536, spec: { serverless: { cloud: 'aws', region: 'us-east-1' } }, suppressConflicts: true, }); } catch (error) { if (error instanceof Errors.PineconeBadRequestError) { // Check error.message: may be quota exceeded (403) or bad params (400) console.error('Index creation failed:', error.message); } throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[12][11]
• deleteIndex · deleteindex-no-error-handling

  error
  Whenpinecone.deleteIndex() called without try-catch or .catch() handler
  ThrowsPineconeBadRequestError (HTTP 403 — "Deletion protection is enabled for this index. Disable deletion protection before retrying."). PineconeNotFoundError (HTTP 404 — index name not found in project). PineconeUnmappedHttpError (HTTP 412 FAILED_PRECONDITION — pending collections exist for the index; must delete collections first). PineconeAuthorizationError (HTTP 401 — bad API key). PineconeConnectionError (network failures).
  Required handlingCaller MUST wrap await pinecone.deleteIndex() in try-catch. Deletion protection errors require explicitly disabling protection first. Not-found errors may be expected in idempotent teardown flows — catch and handle PineconeNotFoundError separately. try { await pinecone.deleteIndex('my-index'); } catch (error) { if (error instanceof Errors.PineconeNotFoundError) { // Index already gone — idempotent, continue return; } if (error instanceof Errors.PineconeBadRequestError) { // Likely deletion protection enabled — disable first console.error('Cannot delete index:', error.message); } throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[13][11]
• inference.embed · inference-embed-no-error-handling

  error
  Whenpc.inference.embed() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — "Invalid API key."). PineconeBadRequestError (HTTP 400 — invalid model name, unsupported parameters, or input_type not supported by the selected model; HTTP 403 — inference quota exceeded for account tier). PineconeInternalServerError (HTTP 500 — Pinecone inference server error). PineconeUnavailableError (HTTP 503 — Pinecone inference service down). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT).
  Required handlingCaller MUST wrap await pc.inference.embed() in try-catch. In RAG pipelines, uncaught embed() failure silently breaks the entire ingestion pipeline — documents are not stored in Pinecone and search quality degrades to zero without alerting. try { const embeddings = await pc.inference.embed({ model: 'multilingual-e5-large', inputs: ['Hello world'], parameters: { inputType: 'passage', truncate: 'END' }, }); return embeddings.data[0].values; } catch (error) { console.error('Embedding generation failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[14][15]
• listPaginated · listpaginated-no-error-handling

  warning
  Whenindex.listPaginated() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — unsupported on pod-based indexes; or HTTP 403 — quota exceeded). PineconeConnectionError (network failures). PineconeArgumentError (runtime validation — invalid arguments).
  Required handlingCaller MUST wrap await index.listPaginated() in try-catch. Pod-based index callers receive PineconeBadRequestError (400) since listPaginated is only supported for serverless indexes. try { const results = await index.listPaginated({ prefix: 'doc1#' }); return results.vectors?.map(v => v.id) ?? []; } catch (error) { console.error('Pinecone listPaginated failed:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[16][17]
• upsertRecords · upsertrecords-no-error-handling

  error
  Whenindex.upsertRecords() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — index does not have integrated inference, or text field exceeds model's max token length; HTTP 403 — inference quota exceeded). PineconeConnectionError (network failures). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.upsertRecords() in try-catch. Failures stop the embedding and storage of records — documents missing from the index will not appear in search results, causing silent knowledge base gaps. try { await index.upsertRecords({ records: [{ id: 'doc-1', chunk_text: 'Hello world' }] }); } catch (error) { console.error('upsertRecords failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[18]
• searchRecords · searchrecords-no-error-handling

  error
  Whenindex.searchRecords() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — index does not have integrated inference, invalid rerank model, or unsupported query format; HTTP 403 — inference quota exceeded). PineconeConnectionError (network failures). PineconeInternalServerError (HTTP 500 — Pinecone server error). PineconeArgumentError (runtime validation — invalid arguments).
  Required handlingCaller MUST wrap await index.searchRecords() in try-catch. Uncaught errors in search cause API routes to return 500 and users get no results, making the RAG system completely unavailable. try { const response = await index.searchRecords({ query: { inputs: { text: 'user query' }, topK: 5 }, fields: ['chunk_text', 'source'], }); return response.result.hits; } catch (error) { console.error('searchRecords failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18]
• startImport · startimport-no-error-handling

  error
  Whenindex.startImport() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid S3 URI, unsupported storage type, or index is not serverless; HTTP 403 — insufficient permissions to access the S3 bucket, or storage import quota exceeded). PineconeConnectionError (network failures). PineconeInternalServerError (HTTP 500 — Pinecone server error). PineconeArgumentError (runtime validation — missing uri parameter).
  Required handlingCaller MUST wrap await index.startImport() in try-catch. Errors here mean no import was started — the S3 data was not ingested. For 403 errors, verify S3 bucket permissions include Pinecone's service account. Store the returned id to poll status. try { const { id } = await index.startImport({ uri: 's3://my-bucket/embeddings/', errorMode: 'CONTINUE', }); console.log(`Import started: ${id}`); } catch (error) { console.error('startImport failed:', error); throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[19]
• deleteAll · deleteall-no-error-handling

  error
  Whenindex.deleteAll() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid namespace or bad request params; HTTP 403 — quota exceeded or forbidden). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error). PineconeUnavailableError (HTTP 503 — Pinecone service down).
  Required handlingCaller MUST wrap await index.deleteAll() in try-catch. This is the highest-stakes Pinecone operation — a single uncaught error during a namespace wipe can leave the application in an inconsistent state or silently prevent a reset from completing. In production reset flows, always verify the delete succeeded. try { await index.deleteAll(); } catch (error) { console.error('Failed to delete all vectors:', error); throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[20][21]
• createIndexForModel · createindexformodel-no-error-handling

  error
  Whenpinecone.createIndexForModel() called without try-catch or .catch() handler
  ThrowsPineconeBadRequestError (HTTP 400 — invalid params: unknown embed model name, unsupported cloud/region, invalid index name; HTTP 403 — project quota exceeded, "Increase your quota or upgrade plan"). PineconeConflictError (HTTP 409 — index name already exists in project). PineconeNotFoundError (HTTP 404 — invalid cloud/region combination). PineconeAuthorizationError (HTTP 401 — bad API key). PineconeConnectionError (network failures). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await pinecone.createIndexForModel() in try-catch. Quota errors (403→PineconeBadRequestError) require account upgrade. Conflict errors (409) can be suppressed with suppressConflicts: true option. Provisioning code that fails to handle these errors leaves the application in a half-initialized state where upsertRecords/searchRecords fail. try { await pinecone.createIndexForModel({ name: 'my-rag-index', cloud: 'aws', region: 'us-east-1', embed: { model: 'llama-text-embed-v2', fieldMap: { text: 'chunk_text' } }, suppressConflicts: true, }); } catch (error) { if (error instanceof Errors.PineconeBadRequestError) { console.error('Index creation failed (quota or bad params):', error.message); } throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[18][12][22]
• deleteNamespace · deletenamespace-no-error-handling

  error
  Whenindex.deleteNamespace() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — bad request params or HTTP 403 — forbidden). PineconeNotFoundError (HTTP 404 — namespace does not exist in the index). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.deleteNamespace() in try-catch. In multi-tenant apps that delete a tenant's namespace on offboarding, an uncaught error leaves stale tenant data in the index and the offboarding flow appears to succeed to the caller. PineconeNotFoundError (namespace already gone) is often acceptable and should be handled separately for idempotent deletion flows. try { await index.deleteNamespace('tenant-123'); } catch (error) { if (error instanceof Errors.PineconeNotFoundError) { // Namespace already deleted — idempotent, continue return; } console.error('Failed to delete namespace:', error); throw error; }
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[23][24][25]
• fetchByMetadata · fetchbymetadata-no-error-handling

  error
  Whenindex.fetchByMetadata() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid filter syntax or bad params; HTTP 403 — quota exceeded). PineconeArgumentError (runtime validation — missing required filter parameter). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.fetchByMetadata() in try-catch. Metadata filter syntax errors throw PineconeBadRequestError at runtime — invalid filter objects are not caught at compile time. Callers must validate filter structure before calling or catch PineconeBadRequestError to handle malformed filters. try { const result = await index.fetchByMetadata({ filter: { status: { '$eq': 'active' } }, limit: 100, }); return result.records; } catch (error) { console.error('fetchByMetadata failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[26][27][28]
• cancelImport · cancelimport-no-error-handling

  warning
  Whenindex.cancelImport() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — bad request params). PineconeNotFoundError (HTTP 404 — import ID does not exist or has expired). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error). Note: Attempting to cancel an already-finished import returns HTTP 200 (no error).
  Required handlingCaller MUST wrap await index.cancelImport() in try-catch. PineconeNotFoundError means the import ID is invalid or expired — handle separately in cleanup flows where the import may have already completed. try { await index.cancelImport(importId); } catch (error) { if (error instanceof Errors.PineconeNotFoundError) { // Import already complete or ID expired — acceptable in cleanup flows return; } console.error('cancelImport failed:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[19][29][30]
• createNamespace · createnamespace-no-error-handling

  warning
  Whenindex.createNamespace() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid namespace name or bad params). PineconeConflictError (HTTP 409 — namespace name already exists on the index). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.createNamespace() in try-catch. PineconeConflictError (409) is the most common error in provisioning code — the namespace may already exist from a previous run. Handle idempotently by catching PineconeConflictError and continuing. try { await index.createNamespace({ name: 'tenant-123', schema: { fields: { category: { filterable: true } } }, }); } catch (error) { if (error instanceof Errors.PineconeConflictError) { // Namespace already exists — idempotent, continue return; } console.error('createNamespace failed:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[23][31][32]
• listImports · listimports-no-error-handling

  warning
  Whenindex.listImports() called without try-catch or .catch() handler
  ThrowsPineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — invalid params). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeInternalServerError (HTTP 500 — Pinecone server error).
  Required handlingCaller MUST wrap await index.listImports() in try-catch. Called in import monitoring dashboards or polling loops; an uncaught error crashes the monitoring flow. Auth failures here indicate the same key used for startImport() is now invalid. try { const { data } = await index.listImports(10); return data ?? []; } catch (error) { console.error('listImports failed:', error); throw error; }
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[19][33][34]
• inference.rerank · inference-rerank-no-error-handling

  error
  Whenpc.inference.rerank() called without try-catch or .catch() handler
  ThrowsPineconeArgumentError (runtime validation BEFORE network call — empty documents array, missing query, or missing/unsupported model name). PineconeAuthorizationError (HTTP 401 — bad API key). PineconeBadRequestError (HTTP 400 — unsupported rerank model, invalid rankFields, or document field mismatch with rankFields; HTTP 403 — inference quota exceeded). PineconeInternalServerError (HTTP 500 — Pinecone inference server error). PineconeUnavailableError (HTTP 503 — inference service down). PineconeConnectionError (network failures: ECONNREFUSED, ETIMEDOUT). PineconeTimeoutError (request exceeded client-configured timeout).
  Required handlingCaller MUST wrap await pc.inference.rerank() in try-catch. In two-stage RAG (vector search + rerank), uncaught rerank failures either crash the API route or, if the caller falls back to the un-reranked candidate list, silently degrade answer quality without any signal to the user or operator. Catch and either retry with backoff (for 5xx/timeout) or fall back to un-reranked top-K with explicit logging so the degraded mode is observable. try { const reranked = await pc.inference.rerank({ model: 'bge-reranker-v2-m3', query: userQuery, documents: candidateDocs, topN: 5, returnDocuments: true, }); return reranked.data; } catch (error) { console.error('Rerank failed:', error); throw error; }
  costmediumin prodimmediate exceptionusers seedegraded performancevisibilitysilent
  Sources[35][36][37]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.