spring-projects/spring-ai · error · AnthropicIoException

Request failed

Error message

Request failed

What it means

SpringAiAnthropicHttpClient.execute wraps any IOException raised while executing the OkHttp call into AnthropicIoException with the message 'Request failed'. This covers connection failures, DNS errors, timeouts, TLS problems and stream read errors during the synchronous HTTP exchange with the Anthropic API.

Source

Thrown at models/spring-ai-anthropic/src/main/java/org/springframework/ai/anthropic/http/okhttp/SpringAiAnthropicHttpClient.java:126

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

	/** Test-only accessor */
	OkHttpClient getOkHttpClient() {
		return this.okHttpClient;
	}

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

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

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

View on GitHub (pinned to 98a7beda4f)

Solutions

1. Check network connectivity and proxy settings to api.anthropic.com (curl https://api.anthropic.com to verify).
2. Inspect the cause (e.getCause() on AnthropicIoException) to distinguish timeout vs. connect vs. TLS failure.
3. Increase OkHttp read/call timeouts for long streaming requests.
4. Add retry with exponential backoff for transient IO errors.

Example fix

// before
Response<ChatResponse> resp = client.chatCompletionRequest(params); // fails on network hiccup
// after
try {
    Response<ChatResponse> resp = client.chatCompletionRequest(params);
} catch (AnthropicIoException e) {
    logger.warn("Transient network failure, retrying", e);
    resp = retryWithBackoff(() -> client.chatCompletionRequest(params));
}

static void assertApiReachable() {
    try (var s = new Socket("api.anthropic.com", 443)) { /* reachable */ }
    catch (IOException e) { throw new IllegalStateException("Anthropic API unreachable: " + e.getMessage()); }
}

try {
    return client.chatCompletionRequest(params);
} catch (AnthropicIoException e) {
    if (e.getCause() instanceof SocketTimeoutException) return retryWithBackoff(...);
    throw e;
}

When it happens

Trigger: Calling any Anthropic API operation through this OkHttp-based client when the TCP connection cannot be established, is reset, times out, or TLS handshake fails; call.execute() or the response body read throws IOException.

Common situations: No network/VPN access or corporate proxy blocking api.anthropic.com; DNS resolution failure; server dropping connections; read timeout set too low for long completions.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

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/7a636ceb776f0895. Report an issue: GitHub.