Package org.a2aproject.sdk.spec

Class A2AClientHTTPError

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

org.a2aproject.sdk.spec.A2AClientError

org.a2aproject.sdk.spec.A2AClientHTTPError

All Implemented Interfaces:

Serializable

public class A2AClientHTTPError
extends A2AClientError

Client exception indicating an HTTP transport error with a specific status code.

This exception is thrown when HTTP communication with an A2A agent fails, capturing both the HTTP status code and error message. It is used for non-2xx HTTP responses that don't contain valid A2A Protocol error responses.

Common HTTP status codes:

• 4xx - Client errors (400 Bad Request, 401 Unauthorized, 404 Not Found, etc.)
• 5xx - Server errors (500 Internal Server Error, 503 Service Unavailable, etc.)

This exception is set as the cause of A2AClientException so that callers can inspect the HTTP status code while remaining backward compatible:

 } catch (A2AClientException e) {
     if (e.getCause() instanceof A2AClientHTTPError httpError) {
         int status = httpError.getCode();
         String body = httpError.getResponseBody();
         Map<String, List<String>> headers = httpError.getResponseHeaders();
         String retryAfter = headers.getOrDefault("Retry-After", List.of())
             .stream().findFirst().orElse(null);
     }
 }
 

See Also:

• for the base client error class
• HTTP Status Codes
• Serialized Form

Constructor Summary

Constructors

Constructor	Description
A2AClientHTTPError(int code, String message, @Nullable String responseBody, Map<String,List<String>> responseHeaders)	Creates a new HTTP client error with the specified status code, message, response body, and headers.

Method Summary

Modifier and Type	Method	Description
int	getCode()	Gets the HTTP status code.
String	getMessage()	Gets the error message.
@Nullable String	getResponseBody()	Returns the raw HTTP response body, if available.
Map<String,List<String>>	getResponseHeaders()	Returns the HTTP response headers.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

A2AClientHTTPError

public A2AClientHTTPError(int code,
 String message,
 @Nullable String responseBody,
 Map<String,List<String>> responseHeaders)

Creates a new HTTP client error with the specified status code, message, response body, and headers.

Parameters:

code - the HTTP status code (e.g. 429, 503)

message - the error message

responseBody - the raw HTTP response body, may be null

responseHeaders - the HTTP response headers

Method Details

getCode

public int getCode()

Gets the HTTP status code.

Returns:

the HTTP status code (e.g. 401, 404, 500, 503)

getMessage

public String getMessage()

Gets the error message.

Overrides:

getMessage in class Throwable

Returns:

the error message

getResponseBody

public @Nullable String getResponseBody()

Returns the raw HTTP response body, if available.

Returns:

the response body, or null if not available

getResponseHeaders

public Map<String,List<String>> getResponseHeaders()

Returns the HTTP response headers.

Useful for examining headers like Retry-After on 429 responses or WWW-Authenticate on 401 responses.

Returns:

unmodifiable, case-insensitive map of header names to lists of values, never null