OpenAI Vector Store — Best Practices

Project Scoping (Most Common Silent Failure)

Vector stores are strictly scoped to the OpenAI project that created them. An API key from Project A cannot read, write, or delete a vector store owned by Project B — it returns 404 or 401, not a permissions error. This is the most common source of confusion.

Checklist when a store returns 404 unexpectedly:

1. List all stores accessible to the active key: client.vectorStores.list(). If the target ID is absent, you're using the wrong key.
2. Compare the key's project (openai-project header in error responses) against the project shown in the OpenAI dashboard for that store.
3. Stores created in the web Playground live in the "Default project" — API access requires a key from that same project.
4. Resources cannot be moved between projects. Either switch keys or re-upload to the correct project.

In multi-key environments (e.g., ~/.env.shared + per-project .env.local):

• The key that runs the upload script and the key the platform uses must belong to the same project.
• When dotenv.config({ path: '.env.local', override: true }) is used in Node.js, it only overrides keys present in .env.local — other keys (like OPENAI_API_KEY) inherit from the shell environment, which may differ from what's in .env.shared.
• Always verify the active key by running client.vectorStores.list() before any destructive operation.