{"record":{"id":"008c09834c19d9f1","repo":"abhigyanpatwari/GitNexus","slug":"embedding-endpoint-returned-err-response-status","errorCode":null,"errorMessage":"Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})","messagePattern":"Embedding endpoint returned (.+?) \\((.+?), batch (.+?)\\)","errorType":"exception","errorClass":"HttpEmbeddingError","httpStatus":null,"severity":"error","filePath":"gitnexus/src/core/embeddings/http-client.ts","lineNumber":574,"sourceCode":"      throw new HttpEmbeddingError(\n        `${err.message} after ${maxAttempts} attempt(s) (${safeUrl(url)}, batch ${batchIndex})`,\n        { cause: err.cause },\n      );\n    }\n    if (err instanceof CircuitOpenError) {\n      throw new HttpEmbeddingError(\n        `Embedding endpoint circuit open (${safeUrl(url)}, batch ${batchIndex}): retry in ${Math.ceil(err.retryAfterMs / 1000)}s`,\n        { cause: err },\n      );\n    }\n    if (err instanceof DOMException && err.name === 'TimeoutError') {\n      throw new HttpEmbeddingError(\n        `Embedding request timed out after ${timeoutMs}ms (${safeUrl(url)}, batch ${batchIndex})`,\n        { cause: err },\n      );\n    }\n    if (err instanceof ResilientFetchExhaustedError) {\n      throw new HttpEmbeddingError(\n        `Embedding endpoint returned ${err.response.status} (${safeUrl(url)}, batch ${batchIndex})`,\n        { cause: err },\n      );\n    }\n    const reason = sanitizeReason(err instanceof Error ? err.message : String(err), url, apiKey);\n    const safeCause = new Error(reason);\n    safeCause.name = err instanceof Error ? err.name : 'EmbeddingTransportError';\n    throw new HttpEmbeddingError(\n      `Embedding request failed (${safeUrl(url)}, batch ${batchIndex}): ${reason}`,\n      { cause: safeCause },\n    );\n  }\n\n  if (!resp.ok) {\n    // resilientFetch already retried 5xx/429; any non-OK response here is\n    // a terminal client error (4xx other than 429).\n    throw new HttpEmbeddingError(\n      `Embedding endpoint returned ${resp.status} (${safeUrl(url)}, batch ${batchIndex})`,","sourceCodeStart":556,"sourceCodeEnd":592,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/ac9a4e9abd8fd3058c070b72c23402a4f887929a/gitnexus/src/core/embeddings/http-client.ts#L556-L592","documentation":"httpEmbedBatch maps ResilientFetchExhaustedError to this message: the endpoint kept returning the same non-2xx HTTP status across all retry attempts (default from GITNEXUS_EMBEDDING_MAX_ATTEMPTS), so the final status is surfaced. Retryable statuses were already retried with backoff before this throws; the status code tells you which class of endpoint problem it is.","triggerScenarios":"401/403 from a wrong or expired GITNEXUS_EMBEDDING_API_KEY; 404 from a wrong URL path or unknown GITNEXUS_EMBEDDING_MODEL; 400 from rejected request shape (bad model, unsupported dims); 429 or 5xx persisting beyond the retry budget.","commonSituations":"API key rotated but env not updated, model deprecation/renaming on the provider, hitting a free-tier rate limit (429) during a full-repo embedding run, or a gateway returning 502 while the backend is down.","solutions":["Read the status: 401/403 → fix GITNEXUS_EMBEDDING_API_KEY; 404 → fix URL path (add /v1) or model name; 400 → check model supports the configured dims; 429 → slow down or raise quota; 5xx → endpoint-side fix.","Verify with curl using the same URL, key, and model as the env vars.","For 429s, set GITNEXUS_EMBEDDING_MIN_INTERVAL_MS to pace requests and/or reduce batch size.","Raise GITNEXUS_EMBEDDING_MAX_ATTEMPTS (≤20) only for genuinely transient 5xx/429 outages."],"exampleFix":"# before\nexport GITNEXUS_EMBEDDING_URL=https://api.example.com\n# after (status 404 -> missing /v1)\nexport GITNEXUS_EMBEDDING_URL=https://api.example.com/v1\nexport GITNEXUS_EMBEDDING_MODEL=text-embedding-3-small\nexport GITNEXUS_EMBEDDING_API_KEY=sk-...","handlingStrategy":"try-catch","validationCode":"const res = await fetch(`${process.env.GITNEXUS_EMBEDDING_URL}/embeddings`, {\n  method: 'POST',\n  headers: { 'content-type': 'application/json', authorization: `Bearer ${process.env.GITNEXUS_EMBEDDING_API_KEY}` },\n  body: JSON.stringify({ model: process.env.GITNEXUS_EMBEDDING_MODEL, input: 'ping' }),\n});\nif (!res.ok) throw new Error(`endpoint precheck failed: ${res.status}`);","typeGuard":"const isEndpointStatusError = (e: unknown): boolean =>\n  e instanceof Error && /Embedding endpoint returned \\d{3}/.test(e.message);","tryCatchPattern":"try {\n  vectors = await httpEmbed(texts);\n} catch (e) {\n  if (isEndpointStatusError(e)) {\n    const status = Number(/returned (\\d{3})/.exec(e.message)![1]);\n    if (status === 401 || status === 403) throw new Error('check GITNEXUS_EMBEDDING_API_KEY');\n    if (status === 404) throw new Error('check GITNEXUS_EMBEDDING_URL path and model name');\n    if (status === 429) { await sleep(backoffMs); return httpEmbed(texts); }\n  }\n  throw e;\n}","preventionTips":["Smoke-test URL + key + model with curl whenever any of the three changes.","Include /v1 in GITNEXUS_EMBEDDING_URL for OpenAI-compatible gateways.","Pace requests (GITNEXUS_EMBEDDING_MIN_INTERVAL_MS) to stay under provider rate limits during full-repo runs."],"tags":["embeddings","http","status-code","authentication","retry-exhausted"],"backgroundTag":"http-error-status","analyzedSha":"ac9a4e9abd8fd3058c070b72c23402a4f887929a","analyzedAt":"2026-08-20T23:29:22.980Z","contentChangedAt":"2026-08-20T23:29:22.980Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}