Package com.tnsai.llm.errors

Class AbstractGoogleErrorMapper

java.lang.Object
com.tnsai.llm.errors.AbstractGoogleErrorMapper
All Implemented Interfaces:
ProviderErrorMapper
Direct Known Subclasses:
GeminiProviderErrorMapper, VertexAIProviderErrorMapper
public abstract class AbstractGoogleErrorMapper extends Object implements ProviderErrorMapper
Shared ProviderErrorMapper for Google Cloud LLM endpoints — the Generative Language API (Gemini) and Vertex AI both return the canonical Google API-Gateway error envelope, shared across every Google Cloud service: 

 {
   "error": {
     "code": 429,
     "message": "Resource has been exhausted (e.g. check quota).",
     "status": "RESOURCE_EXHAUSTED",
     "details": [...]
   }
 }

Google uses canonical google.rpc.Code string statuses (RESOURCE_EXHAUSTED, INVALID_ARGUMENT, …) on top of the HTTP status; both are surfaced. The string status is the more durable signal — Google may shift HTTP codes for the same logical condition, but the canonical status is contract-stable.

Status mappings:

  • UNAUTHENTICATED / PERMISSION_DENIED → AUTHENTICATION_FAILED
  • NOT_FOUND → MODEL_NOT_FOUND
  • RESOURCE_EXHAUSTED / UNAVAILABLE → MODEL_OVERLOADED
  • INTERNAL / DEADLINE_EXCEEDED → SERVER_ERROR
  • INVALID_ARGUMENT / FAILED_PRECONDITION / OUT_OF_RANGE → INVALID_REQUEST, with a message-sniff heuristic for context-length issues
  • HTTP-status fallback when the body has no status string

Note on safety filters: Google's content-filter rejections do not arrive as HTTP errors — the server returns 200 with a block reason populated. That path is the client's concern, not this mapper's.

Since:
0.12.0 (TNS-622 — extracted from GeminiProviderErrorMapper so Vertex AI shares it)

  • 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