Package com.tnsai.llm.errors

Class HuggingFaceProviderErrorMapper

java.lang.Object
com.tnsai.llm.errors.HuggingFaceProviderErrorMapper
All Implemented Interfaces:
ProviderErrorMapper
public class HuggingFaceProviderErrorMapper extends Object implements ProviderErrorMapper
ProviderErrorMapper for HuggingFace Inference API — eleventh pilot mapper.

HuggingFace's error envelope varies across endpoints and model versions: 


 // simple
 { "error": "Authorization header is invalid" }

 // model-loading (HF cold-start; transient)
 { "error": "Model meta-llama/X is currently loading",
   "estimated_time": 30.0 }

 // structured (newer Inference API responses)
 { "error": { "message": "...", "type": "..." } }

Distinctive HF behaviour: cold-start returns HTTP 503 with an estimated_time field — the model is loading, not actually failing. Mapper routes this case to MODEL_OVERLOADED so the consumer's fallback / retry layer treats it as transient backpressure rather than a hard failure. The estimated_time value lands in ProviderDetails.rawBody() for caller-visible delay planning.

Status mappings:

  • "loading" / "currently loading" message + 503 → MODEL_OVERLOADED (cold-start path)
  • "authorization" / "api token" message → AUTHENTICATION_FAILED
  • "rate limit" / "too many requests" → MODEL_OVERLOADED
  • "too many tokens" / "input is too long" → CONTEXT_TOO_LONG
  • "not found" / "does not exist" → MODEL_NOT_FOUND
  • HTTP fallback for unrecognised cases

Captured headers: retry-after, x-request-id, x-compute-type (HF surfaces inference backend type: cpu+optimized, gpu), x-compute-time.

Since:
0.5.3 (issue #87 follow-up — eleventh pilot mapper)

  • Constructor Details

    • HuggingFaceProviderErrorMapper

      public HuggingFaceProviderErrorMapper()

  • Method Details

    • providerId

      public String providerId()
      Specified by:
      providerId in interface ProviderErrorMapper
      Returns:
      short, lowercase provider id (e.g. "openai", "anthropic"). Used to route a raw response to the right mapper.

    • map

      public com.tnsai.exceptions.LLMException map(int httpStatus, Map<String,String> responseHeaders, String responseBody, String model, Throwable cause)
      Description copied from interface: ProviderErrorMapper
      Translate a raw HTTP error response into a typed LLMException.
      Specified by:
      map in interface ProviderErrorMapper
      Parameters:
      httpStatus - HTTP status code from the response
      responseHeaders - selected response headers (lower-cased keys); empty map if none captured
      responseBody - raw response body; mapper parses provider-specific envelope (e.g. JSON error.code)
      model - model identifier from the request, for the resulting LLMException.getModel()
      cause - underlying transport throwable, may be null when the failure is purely a non-2xx response
      Returns:
      typed LLMException with ProviderDetails attached

    • mapErrorType

      public Optional<com.tnsai.exceptions.LLMException.ErrorType> mapErrorType(String providerCode)
      Description copied from interface: ProviderErrorMapper
      Map a provider-native error code to a framework LLMException.ErrorType. Implementations should err on the side of LLMException.ErrorType.UNKNOWN for codes they don't recognize so that a new provider error doesn't fail the whole mapping path.
      Specified by:
      mapErrorType in interface ProviderErrorMapper
      Parameters:
      providerCode - native code (e.g. "context_length_exceeded")
      Returns:
      matching LLMException.ErrorType, or Optional.empty() if the mapper has no opinion