{"record":{"id":"ff8df291118f8d6a","repo":"abhigyanpatwari/GitNexus","slug":"embedding-endpoint-returned-resp-status-safe","errorCode":null,"errorMessage":"Embedding endpoint returned ${resp.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":536,"sourceCode":"    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})`,\n    );\n  }\n\n  if (parsed === undefined) {\n    // Defensively unreachable: an OK response either sets `parsed` or throws\n    // out of `fetchImpl`. Kept so the narrowing holds without a non-null\n    // assertion, and so a future `resilientFetch` change can't return an\n    // unvalidated body silently.\n    throw new HttpEmbeddingError(unparseableMessage());\n  }\n  return parsed;\n};\n\n/**\n * Embed texts via the HTTP backend, splitting into batches.\n * Reads config from env vars on every call.\n *","sourceCodeStart":518,"sourceCodeEnd":554,"githubUrl":"https://github.com/abhigyanpatwari/GitNexus/blob/d540b00184d71a896261ee02670da9a92d59d8f7/gitnexus/src/core/embeddings/http-client.ts#L518-L554","documentation":"An HttpEmbeddingError thrown after the retry loop when resilientFetch returns a non-OK response. Per the inline comment, resilientFetch already retried 5xx and 429, so any non-OK response reaching this point is a terminal client error — a 4xx other than 429. The message reports resp.status. These are not retried because retrying a 401/403/400/404 cannot change the outcome.","triggerScenarios":"httpEmbedBatch after resilientFetch returns a 4xx (non-429) response. Common: 401/403 (bad or missing GITNEXUS_EMBEDDING_API_KEY), 400 (malformed request body, unknown model, or the `dimensions` field rejected by a strict backend), 404 (wrong baseUrl path), 413 (batch body too large), 422 (unprocessable input).","commonSituations":"Missing/expired/typo'd API key (401/403). GITNEXUS_EMBEDDING_MODEL not available on the endpoint (400/404). baseUrl with a wrong path (404). A strict backend rejecting the `dimensions` request field — fix by setting GITNEXUS_EMBEDDING_REQUEST_DIMS=omit while keeping GITNEXUS_EMBEDDING_DIMS at the output width. Inputs exceeding the provider's content limit (413).","solutions":["Match the fix to the status: 401/403 → set a valid GITNEXUS_EMBEDDING_API_KEY; 400/404 → fix GITNEXUS_EMBEDDING_MODEL and GITNEXUS_EMBEDDING_URL; 422/400 on a strict backend → set GITNEXUS_EMBEDDING_REQUEST_DIMS=omit.","Reproduce with curl to see the provider's error body: `curl -i -X POST \"$URL/embeddings\" -H \"Authorization: Bearer $KEY\" -H 'Content-Type: application/json' -d '{\"model\":\"'$MODEL'\",\"input\":\"x\"}'`.","For 413, reduce input size; for 429 see error 130 (rate-limited, retried)."],"exampleFix":"// before: strict backend rejects the `dimensions` request field\nexport GITNEXUS_EMBEDDING_DIMS=1536\nexport GITNEXUS_EMBEDDING_REQUEST_DIMS=1536\n\n// after: declare expected width, suppress the request hint\nexport GITNEXUS_EMBEDDING_DIMS=1536\nexport GITNEXUS_EMBEDDING_REQUEST_DIMS=omit","handlingStrategy":"validation","validationCode":"// Probe and reject known-bad configurations before indexing:\nconst r = await fetch(`${URL}/embeddings`, { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${KEY}` }, body: JSON.stringify({ model: MODEL, input: 'x' }) });\nif (r.status === 401 || r.status === 403) throw new Error('Bad API key');\nif (r.status === 404) throw new Error('Wrong URL or model');\nif (r.status >= 400 && r.status !== 429) throw new Error(`Endpoint rejected probe: ${r.status}`);","typeGuard":"import { isHttpEmbeddingError } from 'gitnexus';\nconst isTerminalStatus = (e: unknown): boolean =>\n  isHttpEmbeddingError(e) &&\n  e instanceof Error &&\n  /^Embedding endpoint returned (4\\d{2}|[45]\\d{2}) /.test(e.message);","tryCatchPattern":"try {\n  await httpEmbed(texts);\n} catch (e) {\n  if (isHttpEmbeddingError(e)) {\n    const m = /returned (\\d{3}) /.exec(e.message);\n    if (m && m[1] !== '429') {\n      // terminal 4xx: fix auth/model/URL; do not retry\n    }\n  }\n  throw e;\n}","preventionTips":["On a strict backend that rejects the `dimensions` request field, set GITNEXUS_EMBEDDING_REQUEST_DIMS=omit while keeping GITNEXUS_EMBEDDING_DIMS set.","Validate GITNEXUS_EMBEDDING_API_KEY, GITNEXUS_EMBEDDING_MODEL, and the URL path with a curl probe before large runs.","Distinguish 429 (rate-limited, retried → error 130) from other 4xx (terminal → this error)."],"tags":["http-status","endpoint","auth","config","embeddings"],"backgroundTag":null,"analyzedSha":"d540b00184d71a896261ee02670da9a92d59d8f7","analyzedAt":"2026-08-12T19:50:25.132Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}