Package com.tnsai.llm.errors

Class AbstractOpenAICompatibleErrorMapper

java.lang.Object
com.tnsai.llm.errors.AbstractOpenAICompatibleErrorMapper
All Implemented Interfaces:
ProviderErrorMapper
Direct Known Subclasses:
CerebrasProviderErrorMapper, DatabricksProviderErrorMapper, DeepInfraProviderErrorMapper, DeepSeekProviderErrorMapper, FireworksAIProviderErrorMapper, LlamaCppServerProviderErrorMapper, LMStudioProviderErrorMapper, NvidiaNIMProviderErrorMapper, PerplexityProviderErrorMapper, QwenCloudProviderErrorMapper, TencentHunyuanProviderErrorMapper, TogetherAIProviderErrorMapper, VLLMProviderErrorMapper, XAIGrokProviderErrorMapper, YiProviderErrorMapper
public abstract class AbstractOpenAICompatibleErrorMapper extends Object implements ProviderErrorMapper
Shared ProviderErrorMapper for providers that clone OpenAI's chat-completions API at the error-envelope level. Subclasses supply only their canonical providerId and human display name; the parsing, error-type mapping and ProviderDetails assembly are identical.

OpenAI-compatible providers (DeepSeek, Together.ai, Fireworks.ai, Perplexity, xAI Grok, DashScope, Cerebras, …) all return the same envelope: 


 { "error": { "message": "...", "type": "...", "code": "...", "param": "..." } }

Native code → LLMException.ErrorType mapping is the OpenAI standard set (the contract these providers advertise compatibility with):

  • context_length_exceeded → CONTEXT_TOO_LONG
  • rate_limit_exceeded / insufficient_quota → MODEL_OVERLOADED
  • invalid_api_key / authentication_error → AUTHENTICATION_FAILED
  • model_not_found → MODEL_NOT_FOUND
  • content_filter / content_policy_violation → CONTENT_FILTERED
  • invalid_request_error → INVALID_REQUEST
  • HTTP-status fallback when the body has no recognised code

A provider that emits an extra native code can override mapErrorType(String) and delegate to super for the common cases; the 15 OpenAI-compatible providers wired in TNS-622 need no such override and are pure two-argument subclasses.

Captured headers: retry-after, x-request-id and any x-ratelimit-* — the rate-limit signals shared across these clones.

Since:
0.12.0 (TNS-622)

  • Method Details

    • providerId

      public final 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