BerriAI/litellm · error · HuggingFaceError

{completion_response[error]}

Error message

{completion_response[error]}

What it means

Raised after successful JSON parsing when the completion response is a dict containing an 'error' key — i.e. HuggingFace answered with a structured error payload (auth failure, model not found, rate limit) instead of generations. The upstream status code and error string are forwarded.

Source

Thrown at litellm/llms/huggingface/embedding/transformation.py:511

            logging_obj.post_call(
                input=request_data,
                api_key=api_key,
                original_response=raw_response.text,
                additional_args={"complete_input_dict": request_data},
            )
            ## RESPONSE OBJECT
            try:
                completion_response = raw_response.json()
                if isinstance(completion_response, dict):
                    completion_response = [completion_response]
            except Exception:
                raise HuggingFaceError(
                    message=f"Original Response received: {raw_response.text}",
                    status_code=raw_response.status_code,
                )

        if isinstance(completion_response, dict) and "error" in completion_response:
            raise HuggingFaceError(
                message=completion_response["error"],
                status_code=raw_response.status_code,
            )
        return self.convert_to_model_response_object(
            completion_response=completion_response,
            model_response=model_response,
            task=task if task is not None and task in hf_task_list else None,
            optional_params=optional_params,
            encoding=encoding,
            messages=messages,
            model=model,
        )

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Act on the forwarded error string and status code.
2. Regenerate the HF token and confirm access to the model on the Hub.
3. For rate/quota errors, add backoff and reduce request rate.

try:
    resp = litellm.completion(...)
except litellm.llms.huggingface.common_utils.HuggingFaceError as e:
    if 'authorization' in str(e).lower():
        rotate_hf_token()  # fetch fresh credential and retry once
    elif 'rate' in str(e).lower():
        backoff_and_retry()
    else:
        raise

When it happens

Trigger: completion() against huggingface where the body parses as JSON like {"error": "Authorization header is invalid"} or {"error": "Model ... does not exist"}.

Common situations: Invalid/expired HF token, referencing a gated model you have not been granted, or hub-side deprecation of the model id.

Related errors

• {embeddings[error]}
• str(e)
• Invalid hf task - {task}. Valid formats - {hf_tasks}.
• response is not in expected format - {completion_response}
• Original Response received: {raw_response.text}

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/b3fe1250121e26f6. Report an issue: GitHub.