Package com.tnsai.llm.errors

Class WatsonxProviderErrorMapper

java.lang.Object
com.tnsai.llm.errors.WatsonxProviderErrorMapper
All Implemented Interfaces:
ProviderErrorMapper
public class WatsonxProviderErrorMapper extends Object implements ProviderErrorMapper
ProviderErrorMapper for IBM watsonx.ai. IBM Cloud services return an errors array rather than OpenAI's single error object: 

 {
   "errors": [ { "code": "json_validation_error", "message": "..." } ],
   "trace": "...",
   "status_code": 400
 }

IBM's native code tokens are not a small stable enum, so this mapper classifies primarily from the HTTP status (the authoritative signal: 429 → overloaded, 5xx → server error, 401/403 → auth) and surfaces the first error's code / message in ProviderDetails for observability rather than guessing a LLMException.ErrorType from it.

Captured headers: retry-after, x-global-transaction-id (IBM's request-correlation id, useful for support tickets).

Since:
0.12.0 (TNS-622)

  • Constructor Details

    • WatsonxProviderErrorMapper

      public WatsonxProviderErrorMapper()

  • 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