Expose HTTP response headers in KoogHttpClientException for rate limit handling

[jay-anbaric]

Currently, KtorKoogHttpClient.processResponse() only captures the body:

  throw KoogHttpClientException(
      clientName = clientName,
      statusCode = response.status.value,
      errorBody = response.bodyAsText(),  // Headers discarded
  )

This forces RetryAfterExtractor implementations to parse retry delays from unstructured error messages, which works for Google Gemini in most cases, but for OpenAI they return rate limit headers, according to https://platform.openai.com/docs/guides/rate-limits.

Rate limits in headers

Field	Sample Value	Description
x-ratelimit-limit-requests	60	The maximum number of requests that are permitted before exhausting the rate limit.
x-ratelimit-limit-tokens	150000	The maximum number of tokens that are permitted before exhausting the rate limit.
x-ratelimit-remaining-requests	59	The remaining number of requests that are permitted before exhausting the rate limit.
x-ratelimit-remaining-tokens	149984	The remaining number of tokens that are permitted before exhausting the rate limit.
x-ratelimit-reset-requests	1s	The time until the rate limit (based on requests) resets to its initial state.
x-ratelimit-reset-tokens	6m0s	The time until the rate limit (based on tokens) resets to its initial state.

For Gemini, we actually had to implement a retryAfterExtractor as the standard message extraction did not pick up Gemini’s rate limit window from the message. But for OpenAI (or other providers) that uses standard response headers to signal rate limit, it seems there is no straightforward way to extract this?

koog = "0.6.0"

[miguelmanlyx]

@jay-anbaric
I see you're dealing with rate limit handling without HTTP headers. We've found this usually happens when retry-after info isn't accessible. When I hit this, I use an AI Badgr receipt to inspect retry attempts and retry-after handling.

[aozherelyeva]

Hi @jay-anbaric,
Thank you for bringing this up. It indeed seems that currently KoogHttpClientException only captures the response body.

I have created a YouTrack issue to address this in the library by including headers in the exception. You can track the progress here.

Until a fix is released, you can intercept the response using a custom Ktor's HttpResponseValidator when configuring your client. This allows you to capture headers before the exception is thrown:

val client = HttpClient {
    expectSuccess = true
    HttpResponseValidator {
        validateResponse { response ->
            if (response.status.value == 429) {
                val retryAfter = response.headers["x-ratelimit-reset-requests"]
                // Log or store the header value to be accessed by your RetryAfterExtractor
            }
        }
    }
}