Package com.tnsai.llm.errors

Class OpenRouterProviderErrorMapper

java.lang.Object
com.tnsai.llm.errors.OpenRouterProviderErrorMapper
All Implemented Interfaces:
ProviderErrorMapper
public class OpenRouterProviderErrorMapper extends Object implements ProviderErrorMapper
ProviderErrorMapper for OpenRouter — eighth pilot mapper.

OpenRouter's envelope is OpenAI-compatible at the wrapper but extends with a metadata object that carries the upstream provider's raw response (since OpenRouter is a routing layer in front of many model providers): 


 {
   "error": {
     "code": 429,                    // numeric HTTP-style or string code
     "message": "Rate limited",
     "metadata": {
       "raw": "...",                 // upstream provider's raw error
       "provider_name": "anthropic"  // which upstream returned the error
     }
   }
 }

Two parser branches: error.code can be either a numeric status code (in which case HTTP routing applies) or a string code (OpenRouter passes through provider-native codes for some conditions). Mapper handles both shapes; numeric values land in ProviderDetails.httpStatus(), string values in ProviderDetails.providerCode().

Upstream-provider name from metadata.provider_name is surfaced as ProviderDetails.providerType() so consumers with a fallback chain can route on "the upstream Anthropic was rate-limited; try a different OpenRouter route".

Status mappings (string-code branch):

  • rate_limit_exceeded → MODEL_OVERLOADED
  • context_length_exceeded → CONTEXT_TOO_LONG
  • model_not_found → MODEL_NOT_FOUND
  • invalid_api_key → AUTHENTICATION_FAILED
  • insufficient_credits → MODEL_OVERLOADED (OpenRouter- specific: caller's balance is too low to route)

Captured headers: retry-after, x-ratelimit-*, x-or-request-id, openrouter-model-id.

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

  • Constructor Details

    • OpenRouterProviderErrorMapper

      public OpenRouterProviderErrorMapper()

  • 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