Expose structured WatsonX API errors and fix retry behavior in watsonx-go

[sbpolar]

Background

WatsonX APIs return detailed, structured error responses when requests fail, including:

• HTTP status codes (e.g., 400, 401, 403, 429, 5xx)
• API-specific error codes and messages
• Optional trace IDs for debugging

Currently, the watsonx-go client:

1. Converts all failures into a generic error (e.g., 400 Bad Request)
2. Does not propagate structured WatsonX error details
3. Fails to support safe retries when the request body is consumed on the first attempt

This leads to incomplete or misleading error information for callers and makes implementing reliable retry logic difficult.

---

Problem

• WatsonX API error responses are not propagated to the caller
• HTTP status codes are effectively masked
• Retry logic fails: the first attempt returns the correct WatsonX error, but subsequent attempts return 400 Bad Request because the HTTP request body has already been consumed
• Client applications cannot reliably inspect, log, or act on WatsonX-specific error details

---

Proposed Solution

1. Structured error propagation

   • Return non-2xx WatsonX HTTP responses as structured errors
   • Include HTTP status codes, error codes, and trace IDs in the returned error
   • Implement Error() for human-readable logging, while allowing type inspection via errors.As

2. Safe retry support

   • Ensure HTTP request bodies are reusable across retry attempts
   • Avoid hardcoding retry logic based on error strings; instead, use status codes and structured errors to decide retryable cases

---

Benefits

• Provides detailed WatsonX API errors to clients
• Supports safe retries for transient failures (e.g., 429, 5xx)
• Preserves HTTP status codes and error information for inspection
• Maintains backward compatibility for generic error handling

---

Notes / References

• PR expose watsonx API errors to callers sbpolar/watsonx-go#1 demonstrates structured WatsonX error propagation using the DecodeWatsonxError function.
• The current retry.go implementation fails on retries because the HTTP request body is consumed after the first attempt.