spring-projects/spring-ai · critical · OpenAIIoException

Request failed

Error message

Request failed

What it means

SpringAiOpenAiHttpClient.execute performs the OkHttp call synchronously; any IOException (DNS failure, connect timeout, socket reset, TLS error) is wrapped in an OpenAIIoException with the message 'Request failed' and the original exception as cause.

Source

Thrown at models/spring-ai-openai/src/main/java/org/springframework/ai/openai/http/okhttp/SpringAiOpenAiHttpClient.java:119

		this.ownsDispatcherExecutor = ownsDispatcherExecutor;
	}

	public OkHttpClient getOkHttpClient() {
		return this.okHttpClient;
	}

	public static Builder builder() {
		return new Builder();
	}

	@Override
	public HttpResponse execute(HttpRequest request, RequestOptions requestOptions) {
		Call call = newCall(request, requestOptions);
		try {
			return toHttpResponse(call.execute());
		}
		catch (IOException e) {
			throw new OpenAIIoException("Request failed", e);
		}
		finally {
			HttpRequestBody body = request.body();
			if (body != null) {
				body.close();
			}
		}
	}

	@Override
	public CompletableFuture<HttpResponse> executeAsync(HttpRequest request, RequestOptions requestOptions) {
		CompletableFuture<HttpResponse> future = new CompletableFuture<>();

		Call call = newCall(request, requestOptions);
		call.enqueue(new Callback() {
			@Override
			public void onResponse(Call call, Response response) {
				future.complete(toHttpResponse(response));

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Inspect the cause chain (e.getCause()) to find the underlying IOException and its concrete reason.
2. Verify network reachability and the configured base URL / proxy settings.
3. Increase connect/read timeouts in the client builder and add retry with backoff for transient IO errors.

Example fix

try {
    return client.execute(request, requestOptions);
}
catch (OpenAIIoException e) {
    logger.warn("OpenAI request failed: {}", e.getCause() == null ? e.getMessage() : e.getCause().getMessage());
    throw e;
}

// pre-flight
InetAddress.getByName("api.openai.com"); // fails fast if DNS/network is broken

try {
    return model.call(request);
} catch (OpenAIIoException e) {
    Throwable cause = e.getCause();
    if (cause instanceof java.net.SocketTimeoutException) {
        // retry with backoff or increase timeouts
    }
    throw new UpstreamUnavailableException("OpenAI request failed", e);
}

When it happens

Trigger: Any OpenAI API call through the OkHttp client when the HTTP layer throws IOException — network outage, wrong base URL, proxy/firewall blocking, TLS handshake failure, or read/write timeout.

Common situations: Corporate proxies without proxy configuration, VPN dropping mid-request, DNS not resolving api.openai.com, or overly aggressive timeouts on large requests.

Related errors

• Request failed
• Failed to write request body
• Could not read content length
• Failed to write request body
• Failed to read audio speech response

AI-assisted analysis of spring-projects/spring-ai@98a7beda4f (2026-09-11). Data as JSON: /api/errors/67b8160255731476. Report an issue: GitHub.