{"record":{"id":"1fde029a19d67336","repo":"chroma-core/chroma","slug":"response-status-response-statustext","errorCode":null,"errorMessage":"${response.status}: ${response.statusText}","messagePattern":"\\$\\{response\\.status\\}: \\$\\{response\\.statusText\\}","errorType":"http","errorClass":"ChromaServerError","httpStatus":500,"severity":"error","filePath":"clients/new-js/packages/chromadb/src/chroma-fetch.ts","lineNumber":142,"sourceCode":"        ) {\n          throw error;\n        }\n        throw new ChromaClientError(\n          `Unprocessable Entity: ${response.statusText}`,\n        );\n      }\n    case 429:\n      const rateLimitBody = await getErrorBody(response);\n      if (rateLimitBody.error === \"Backoff\") {\n        throw new ChromaBackoffError(\n          rateLimitBody.message || \"Backoff and retry\",\n        );\n      }\n      throw new ChromaRateLimitError(\"Rate limit exceeded\");\n  }\n\n  const errorMessage = await getErrorMessage(response);\n  throw new ChromaServerError(errorMessage);\n};\n","sourceCodeStart":124,"sourceCodeEnd":144,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/clients/new-js/packages/chromadb/src/chroma-fetch.ts#L124-L144","documentation":"Thrown by chromaFetch (chroma-fetch.ts:142) as a ChromaServerError for any non-OK status not handled by the 400/401/403/404/409/412/422/429 switch — in practice HTTP 5xx. The message comes from getErrorMessage(): the body's message or error field if present, else the raw `${status}: ${statusText}` fallback, which is what you see when the error body is empty or not JSON (e.g. a 502/504 HTML page from a proxy).","triggerScenarios":"Chroma server crashes (500), unhandled server bugs, maintenance restarts, or infrastructure-layer 502/503/504 from load balancers and proxies in front of Chroma when the upstream is down or timing out.","commonSituations":"Long ingestion jobs hitting a server OOM/restart; Kubernetes pod recycling while clients are connected; nginx returning '504: Gateway Time-out' when chroma is overloaded; version-skew server panics on new payloads.","solutions":["Check Chroma server health/logs (docker logs, pod events) for the root cause of the 5xx.","Retry with exponential backoff — 5xx and gateway errors are usually transient, especially 502/503/504.","If '504'-style timeouts repeat under load, reduce batch sizes or scale the server (more replicas/CPU/memory).","Verify client/server version compatibility if a deterministic 500 occurs on a specific call."],"exampleFix":"// before\nawait collection.query({ queryTexts: [\"x\"] }); // occasional 502/504 from gateway\n\n// after\nasync function withRetry<T>(fn: () => Promise<T>, tries = 5): Promise<T> {\n  for (let i = 0; ; i++) {\n    try { return await fn(); }\n    catch (e) {\n      if (e instanceof ChromaServerError && i < tries - 1) {\n        await new Promise(r => setTimeout(r, 2 ** i * 250 + Math.random() * 250));\n        continue;\n      }\n      throw e;\n    }\n  }\n}\nawait withRetry(() => collection.query({ queryTexts: [\"x\"] }));","handlingStrategy":"retry","validationCode":"async function healthy(url: string): Promise<boolean> {\n  try { return (await fetch(`${url}/api/v2/heartbeat`)).ok; } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"for (let attempt = 0; ; attempt++) {\n  try {\n    return await operation();\n  } catch (e) {\n    const transient = e instanceof ChromaServerError && !/\\b5[0-9]{2}\\b.*[Pp]anic/.test(e.message);\n    if (transient && attempt < 5) {\n      await new Promise(r => setTimeout(r, 2 ** attempt * 250 + Math.random() * 250));\n      continue;\n    }\n    throw e;\n  }\n}","preventionTips":["Wrap all Chroma calls in exponential-backoff retry for 5xx/gateway errors.","Monitor server health (heartbeat + container logs) so transient 5xx are explained.","Right-size batches and server resources to avoid overload-induced 504/503."],"tags":["http-5xx","server-error","gateway","retryable","transient"],"backgroundTag":"internal-server-error","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}