HKUDS/DeepTutor · error · EmbeddingProviderError

Embedding provider returned HTTP {response.status_code}

Error message

Embedding provider returned HTTP {response.status_code}

What it means

The embeddings endpoint returned an HTTP status >= 400 that is not one of the recoverable cases (the 429 key-rotation path and the encoding_format=400 auto-retry already ran). The full body is attached to the EmbeddingProviderError for diagnosis.

Source

Thrown at deeptutor/services/embedding/adapters/openai_compatible.py:285

                            model=model,
                            url=url,
                            provider="openai_compat",
                        )

                    if response.status_code >= 400:
                        body_text = response.text
                        if "encoding_format" not in payload and rejects_absent_encoding_format(
                            response.status_code, body_text
                        ):
                            payload["encoding_format"] = "float"
                            logger.info(
                                "Gateway requires an explicit `encoding_format`; "
                                "retrying once with 'float' (%s)",
                                url,
                            )
                            continue
                        logger.error(f"HTTP {response.status_code} from {url}: {body_text[:2000]}")
                        raise EmbeddingProviderError(
                            f"Embedding provider returned HTTP {response.status_code}",
                            status=response.status_code,
                            body=body_text,
                            model=model,
                            url=url,
                            provider="openai_compat",
                        )

                    # A 2xx response with non-JSON body usually means the
                    # endpoint/model pairing is wrong or a gateway routed us to
                    # an HTML page. Surface that as structured diagnostics.
                    try:
                        data = response.json()
                    except (json.JSONDecodeError, ValueError) as exc:
                        body_text = response.text
                        content_type = response.headers.get("content-type", "")
                        body_preview = body_text.strip()[:200] or "<empty body>"
                        hint = ""

View on GitHub (pinned to 3e82f13042)

Solutions

  1. Read err.body — it contains the provider's error text (first 2000 chars logged as well)
  2. 401/403: fix the API key / Azure api-version; 404: fix base_url or model name; 400: check whether `dimensions` or other params must be disabled (set send_dimensions=False)
  3. 5xx: retry later or switch gateway endpoint
  4. Reproduce with curl using the same payload to isolate adapter vs provider

Example fix

# before: gateway 400s on `dimensions`
embedding_binding = {model: "some-model", dimensions: 1024}
# after
embedding_binding = {model: "some-model", dimensions: 1024, send_dimensions: false}
Defensive patterns

Strategy: try-catch

Validate before calling

null

Type guard

null

Try / catch

try:
    resp = await adapter.embed(req)
except EmbeddingProviderError as e:
    if e.status and 400 <= e.status < 500:
        log.error("config error: %s body=%s", e, e.body)
        raise ConfigurationError(e.body) from e
    if e.status and e.status >= 500:
        await asyncio.sleep(backoff); retry()
    raise

Prevention

When it happens

Trigger: 400 for unsupported `dimensions` param on models that reject it; 401/403 for bad API key; 404 for wrong base_url or model; 500/502/503 gateway failures — after the automatic encoding_format retry did not match.

Common situations: Configuring dimensions on a non-OpenAI model whose gateway rejects the param; Azure deployments missing api-version; expired key; proxy routing to wrong backend.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/db20d89bff28c932. Report an issue: GitHub.