chroma-core/chroma · error · RuntimeError

Failed to get embeddings from Chroma Cloud API: HTTP {e.resp

Error message

Failed to get embeddings from Chroma Cloud API: HTTP {e.response.status_code} - {e.response.text}

What it means

In __call__, the POST to the /embed_sparse endpoint is wrapped in try/except; when httpx reports raise_for_status() failed (HTTPStatusError) the function raises RuntimeError embedding the status code and response body. This is the path for any 4xx/5xx reply from the Chroma Cloud sparse embedding API, so the server's own error text travels with the exception.

Source

Thrown at chromadb/utils/embedding_functions/chroma_cloud_splade_embedding_function.py:104

        if not input:
            return []

        payload: Dict[str, Union[str, Documents]] = {
            "texts": list(input),
            "task": "",
            "target": "",
            "fetch_tokens": "true" if self.include_tokens is True else "false",
        }

        try:
            import httpx

            response = self._session.post(self._api_url, json=payload, timeout=60)
            response.raise_for_status()
            json_response = response.json()
            return self._parse_response(json_response)
        except httpx.HTTPStatusError as e:
            raise RuntimeError(
                f"Failed to get embeddings from Chroma Cloud API: HTTP {e.response.status_code} - {e.response.text}"
            )
        except httpx.TimeoutException:
            raise RuntimeError("Request to Chroma Cloud API timed out after 60 seconds")
        except httpx.HTTPError as e:
            raise RuntimeError(f"Failed to get embeddings from Chroma Cloud API: {e}")
        except Exception as e:
            raise RuntimeError(f"Unexpected error calling Chroma Cloud API: {e}")

    def _parse_response(self, response: Any) -> SparseVectors:
        """
        Parse the response from the Chroma Cloud Sparse Embedding API.
        """
        raw_embeddings = response["embeddings"]

        # Normalize each sparse vector (sort indices and validate)
        normalized_vectors: SparseVectors = []
        for emb in raw_embeddings:

View on GitHub (pinned to aecdd12c8a)

Solutions

Parse the status from the message: 401/403 -> refresh CHROMA_API_KEY and restart; 429 -> slow down or batch smaller; 5xx -> retry with backoff later.
Verify the token and model by reproducing the request (the headers are x-chroma-token and x-chroma-embedding-model) with curl.
Add exponential backoff for 429/5xx and treat 4xx as non-retryable.
Check Chroma Cloud status pages if 5xx persists.

Example fix

# before
vecs = ef(["hello"])  # RuntimeError: ... HTTP 429 - rate limited

# after
import time
for attempt in range(5):
    try:
        vecs = ef(["hello"])
        break
    except RuntimeError as e:
        if "HTTP 4" in str(e) or attempt == 4:
            raise  # client errors: fix credentials/payload, don't retry
        time.sleep(2 ** attempt)

Defensive patterns

Strategy: try-catch

Try / catch

import time

def embed_with_handling(ef, texts, max_retries=5):
    for attempt in range(max_retries + 1):
        try:
            return ef(texts)
        except RuntimeError as e:
            msg = str(e)
            if "HTTP 401" in msg or "HTTP 403" in msg:
                raise PermissionError(msg) from e          # fix credentials, no retry
            if "HTTP 4" in msg:
                raise ValueError(msg) from e               # bad request, no retry
            if attempt == max_retries:
                raise
            time.sleep(min(2 ** attempt, 30))             # 429/5xx: back off and retry

Prevention

Add exponential backoff with jitter for 429/5xx around every cloud embed call.
Treat 401/403 as fatal credential events and alert on them.
Batch ingestion adaptively: shrink batch size after 429s.

When it happens

Trigger: Calling ef(texts) and the API returns an error status: 401/403 for a bad or expired x-chroma-token, 400 for malformed payload or unsupported model header, 429 for rate limiting, 5xx for server-side failures.

Common situations: Expired or revoked API key in a long-running service; rate limits hit during bulk ingestion; Chroma Cloud incidents returning 502/503; a model header value the backend no longer accepts.

Related errors

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