chroma-core/chroma · error · ChromaQuotaExceededError

Quota exceeded

Error message

Quota exceeded

What it means

Thrown by chromaFetch (chroma-fetch.ts:117) as a ChromaQuotaExceededError when the server returns 422 with a message beginning 'Quota exceeded' or 'Billing limit exceeded'. This is Chroma Cloud telling you a hard usage or spending limit has been reached and writes (or all operations) are rejected until the quota resets or the limit is raised.

Source

Thrown at clients/new-js/packages/chromadb/src/chroma-fetch.ts:117

      const preconditionBody = await getErrorBody(response);
      if (preconditionBody.error === "StaleReadError") {
        throw new ChromaStaleReadError(
          preconditionBody.message || "stale read",
        );
      }
      throw new ChromaClientError(
        preconditionBody.message || "Precondition Failed",
      );
    case 422:
      try {
        const body = await response.json();
        if (
          body &&
          body.message &&
          (body.message.startsWith("Quota exceeded") ||
            body.message.startsWith("Billing limit exceeded"))
        ) {
          throw new ChromaQuotaExceededError(body?.message);
        }
        throw new ChromaClientError(body?.message || "Unprocessable Entity");
      } catch (error) {
        if (
          error instanceof ChromaQuotaExceededError ||
          error instanceof ChromaClientError
        ) {
          throw error;
        }
        throw new ChromaClientError(
          `Unprocessable Entity: ${response.statusText}`,
        );
      }
    case 429:
      const rateLimitBody = await getErrorBody(response);
      if (rateLimitBody.error === "Backoff") {
        throw new ChromaBackoffError(
          rateLimitBody.message || "Backoff and retry",

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Check the Chroma Cloud console for which quota/limit fired and when it resets.
2. Raise the billing/usage limit or upgrade the plan if the usage is legitimate.
3. Pause ingestion and resume after reset, making the job resumable/idempotent.
4. Catch ChromaQuotaExceededError to stop retry storms — retrying will not help until the quota clears.

Example fix

// before
for (const batch of batches) await collection.add(batch); // dies mid-loop with QuotaExceededError

// after
for (const batch of batches) {
  try {
    await collection.add(batch);
  } catch (e) {
    if (e instanceof ChromaQuotaExceededError) { await pauseUntilQuotaReset(); continue; }
    throw e;
  }
}

try {
  await collection.add(batch);
} catch (e) {
  if (e instanceof ChromaQuotaExceededError) {
    // stop retrying immediately; persist progress, alert ops, wait for reset or limit raise
  }
  throw e;
}

When it happens

Trigger: Any write/query against Chroma Cloud after the tenant hit its storage, request, or billing cap; end-of-month limits on free tiers; a burst of ingestion crossing a spending ceiling mid-run.

Common situations: Free-tier projects exhausting monthly units; production ingestion jobs hitting spend limits; quota changed by an admin without notifying the app team.

Related errors

• Your API key does not have access to any DBs for tenant ${th
• Your API key is scoped to more than 1 DB. Please provide a D
• Unprocessable Entity
• Unprocessable Entity: ${response.statusText}
• Backoff and retry

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/e7063f6d2cf61f90. Report an issue: GitHub.