[ENH] Better JS client error messaging

[kylediaz]

This is a simple script that simulates a naive mass upload to Chroma that will trigger our rate limiter

import { CloudClient } from "chromadb";

const client = new CloudClient({
  apiKey: "...",
  tenant: "...",
  database: "test-db",
});

async function run() {
  const collection = await client.getOrCreateCollection({
    name: "ratelimit_test",
  })

  for (let i = 0; i < 100; i++) {
    collection.upsert({
      ids: [i.toString()],
      documents: [`Document ${i}`],
    });
  }
}

run();

Users will get a vague "unable to connect" error:

/Users/kylediaz/Repos/chroma-core/smokey/node_modules/.pnpm/[email protected]/node_modules/chromadb/dist/cjs/chromadb.cjs:1749
  throw new ChromaConnectionError(
        ^


ChromaConnectionError: Unable to connect to the chromadb server. Please try again later.
    at chromaFetch (/Users/kylediaz/Repos/chroma-core/smokey/node_modules/.pnpm/[email protected]/node_modules/chromadb/dist/cjs/chromadb.cjs:1749:9)
    at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
    at async o (/Users/kylediaz/Repos/chroma-core/smokey/node_modules/.pnpm/[email protected]/node_modules/chromadb/dist/cjs/chromadb.cjs:397:26)
    at async _CollectionImpl.upsert (/Users/kylediaz/Repos/chroma-core/smokey/node_modules/.pnpm/[email protected]/node_modules/chromadb/dist/cjs/chromadb.cjs:1644:5) {
  cause: undefined
}

Node.js v22.15.0

This PR adds a special error message when hitting a rate limit, and it shows the response status for all other cases to cover anything we may have missed

[kylediaz]

• [ENH] Better JS client error messaging #4944 👈 (View in Graphite)
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[github-actions]

Reviewer Checklist

Please leverage this checklist to ensure your code review is thorough before approving

Testing, Bugs, Errors, Logs, Documentation

• Can you think of any use case in which the code does not behave as intended? Have they been tested?
• Can you think of any inputs or external events that could break the code? Is user input validated and safe? Have they been tested?
• If appropriate, are there adequate property based tests?
• If appropriate, are there adequate unit tests?
• Should any logging, debugging, tracing information be added or removed?
• Are error messages user-friendly?
• Have all documentation changes needed been made?
• Have all non-obvious changes been commented?

System Compatibility

• Are there any potential impacts on other parts of the system or backward compatibility?
• Does this change intersect with any items on our roadmap, and if so, is there a plan for fitting them together?

Quality

• Is this code of a unexpectedly high quality (Readability, Modularity, Intuitiveness)

[propel-code-bot]

This PR enhances error handling in the Chroma JavaScript client by detecting HTTP 429 responses (rate limits) and throwing a specific ChromaRateLimitError, rather than the previous generic connection error. Additionally, all other unexpected responses now include the HTTP status in their error messages for clearer diagnostics.

This summary was automatically generated by @propel-code-bot