BerriAI/litellm · error · VertexAIError

{err.response.text}

Error message

{err.response.text}

What it means

The async multimodal embedding path (litellm.aembedding with vertex_ai/multimodalembedding@001) wraps HTTP failures: httpx raise_for_status() raises HTTPStatusError, which litellm re-raises as VertexAIError carrying the upstream status code and raw response body. Unlike image generation's bare Exception, this is a typed error — inspect .status_code and .message to branch on the cause.

Source

Thrown at litellm/llms/vertex_ai/multimodal_embeddings/embedding_handler.py:175

        if client is None:
            _params: Final = {}
            if timeout is not None:
                if isinstance(timeout, float) or isinstance(timeout, int):
                    timeout = httpx.Timeout(timeout)
                _params["timeout"] = timeout
            client = get_async_httpx_client(
                llm_provider=litellm.LlmProviders.VERTEX_AI,
                params={"timeout": timeout},
            )
        else:
            client = client

        try:
            response: Final = await client.post(api_base, headers=headers, json=data)
            response.raise_for_status()
        except httpx.HTTPStatusError as err:
            error_code: Final = err.response.status_code
            raise VertexAIError(status_code=error_code, message=err.response.text)
        except httpx.TimeoutException:
            raise VertexAIError(status_code=408, message="Timeout error occurred.")

        return vertex_multimodal_embedding_handler.transform_embedding_response(
            model=model,
            raw_response=response,
            model_response=model_response,
            logging_obj=logging_obj,
            api_key=api_key,
            request_data=data,
            optional_params=optional_params,
            litellm_params=litellm_params,
        )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Catch VertexAIError and read .status_code and .message to identify the upstream cause
2. 403/404: enable the multimodalembedding model and verify the model name in your region
3. 400: validate instances — supported dimensions only, valid base64/GCS URIs, text within token limits
4. 401: refresh credentials (re-run gcloud auth application-default login or rotate the SA key)
5. Verify the service account has storage.objects.get access for gs:// image inputs

Example fix

# before
resp = await litellm.aembedding(
    model='vertex_ai/multimodalembedding@001',
    input=['a cat', 'gs://my-bucket/cat.png'],
)

# after
from litellm.exceptions import APIError
try:
    resp = await litellm.aembedding(
        model='vertex_ai/multimodalembedding@001',
        input=['a cat', 'gs://my-bucket/cat.png'],
        vertex_ai_project='my-project',
        vertex_ai_location='us-central1',
    )
except Exception as e:
    status = getattr(e, 'status_code', None)
    if status == 403:
        raise RuntimeError('Enable Vertex AI API and check IAM') from e
    raise

def valid_multimodal_instances(inputs) -> bool:
    return all(isinstance(x, str) and x for x in inputs)

assert valid_multimodal_instances(inputs), 'inputs must be non-empty text/gs:// URIs/base64 strings'

try:
    resp = await litellm.aembedding(model='vertex_ai/multimodalembedding@001', input=inputs)
except Exception as e:
    status = getattr(e, 'status_code', None)
    if status == 400:
        raise ValueError('invalid instance payload (dimensions/base64/token limit)') from e
    if status in (401, 403):
        raise RuntimeError('credentials/IAM problem — check API enablement and roles') from e
    raise

When it happens

Trigger: await litellm.aembedding(model='vertex_ai/multimodalembedding@001', input=['a cat', 'gs://bucket/cat.png']) returning 400 (invalid instance — e.g. bad outputDimensionality, malformed base64, text over the model's token limit), 401 (expired access token), 403 (Vertex AI API not enabled / no predict permission), or 404 (model name typo like multimodalembedding@002).

Common situations: Forgetting to enable the Vertex AI API in the project; passing an unsupported dimensions value via map_openai_params; expired tokens after long-running processes cache credentials; gs:// URIs the service account cannot read.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• Error: {response.status_code} {response.text}
• {custom_llm_provider.capitalize()}Exception BadRequestError
• GCP IAM authentication failed
• google-cloud-iam is required for GCP IAM Redis authenticatio
• litellm.BadRequestError: {custom_llm_provider}Exception - {e

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/5e0da86385478ca4. Report an issue: GitHub.