Package com.tnsai.llm.errors

Interface ProviderErrorMapper

All Known Implementing Classes:

AbstractGoogleErrorMapper, AbstractOpenAICompatibleErrorMapper, AnthropicProviderErrorMapper, AzureOpenAIProviderErrorMapper, BedrockProviderErrorMapper, CerebrasProviderErrorMapper, CohereProviderErrorMapper, DatabricksProviderErrorMapper, DeepInfraProviderErrorMapper, DeepSeekProviderErrorMapper, FireworksAIProviderErrorMapper, GeminiProviderErrorMapper, GroqProviderErrorMapper, HuggingFaceProviderErrorMapper, LlamaCppServerProviderErrorMapper, LMStudioProviderErrorMapper, MiniMaxProviderErrorMapper, MistralProviderErrorMapper, NvidiaNIMProviderErrorMapper, OllamaProviderErrorMapper, OpenAIProviderErrorMapper, OpenRouterProviderErrorMapper, PerplexityProviderErrorMapper, QwenCloudProviderErrorMapper, ReplicateProviderErrorMapper, TencentHunyuanProviderErrorMapper, TogetherAIProviderErrorMapper, VertexAIProviderErrorMapper, VLLMProviderErrorMapper, WatsonxProviderErrorMapper, XAIGrokProviderErrorMapper, YiProviderErrorMapper, ZhipuAIProviderErrorMapper

public interface ProviderErrorMapper

Provider-specific translation from a raw HTTP error response to a typed LLMException with attached ProviderDetails.

One implementation per provider (OpenAI, Anthropic, Gemini, Ollama, AWS Bedrock, Cohere, Groq, HuggingFace, Azure OpenAI, OpenRouter, MiniMax, ZhipuAI, ...). Each mapper owns the parsing of its provider's error envelope (different shapes — OpenAI nests under error, Anthropic uses type/error, etc.) and the mapping from that provider's native code → LLMException.ErrorType.

Why an SPI

Providers add new error codes over time. Hardcoding a switch statement in AbstractLLMClient would force a framework release for every new provider code. SPI lets each provider's mapper evolve independently — and lets third-party providers ship their own mapper without modifying the framework.

Discovery

Mappers are discovered via ServiceLoader; the framework looks up the matching mapper by providerId() when an LLM client throws. No mapper found → fall back to a generic LLMException.ErrorType.UNKNOWN.

Since:

0.5.0 (issue #87)

Method Summary

Modifier and Type	Method	Description
com.tnsai.exceptions.LLMException	map(int httpStatus, Map<String,String> responseHeaders, String responseBody, String model, Throwable cause)	Translate a raw HTTP error response into a typed LLMException.
Optional<com.tnsai.exceptions.LLMException.ErrorType>	mapErrorType(String providerCode)	Map a provider-native error code to a framework LLMException.ErrorType.
String	providerId()

Method Details

providerId

String providerId()

Returns:

short, lowercase provider id (e.g. "openai", "anthropic"). Used to route a raw response to the right mapper.

map

com.tnsai.exceptions.LLMException map(int httpStatus,
 Map<String,String> responseHeaders,
 String responseBody,
 String model,
 Throwable cause)

Translate a raw HTTP error response into a typed LLMException.

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

Optional<com.tnsai.exceptions.LLMException.ErrorType> mapErrorType(String providerCode)

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.

Parameters:

providerCode - native code (e.g. "context_length_exceeded")

Returns:

matching LLMException.ErrorType, or Optional.empty() if the mapper has no opinion