In Java 11 and later, add a custom request header with HttpRequest.Builder.header(name, value), build the request, and send it with HttpClient. Use setHeader when a later value must replace an earlier one. For Java 8-era code, call HttpURLConnection.setRequestProperty before any operation that opens the connection. The examples below show complete GET, POST, asynchronous, timeout, replacement, and troubleshooting patterns.
Choose the Java HTTP API first
The right header method depends mainly on your Java runtime and whether you already have a client abstraction in production.
| Approach | Java requirement | Sending model | Header behavior | Timeout and errors | Configuration |
|---|---|---|---|---|---|
JDK HttpClient |
Java 11 or newer | Blocking send or asynchronous sendAsync |
header adds a value; setHeader replaces values for that name |
Client connect timeout, request timeout, returned status, and exceptions | Builder-based and explicit |
HttpURLConnection/URLConnection |
Available in older JDKs, including Java 8 designs | Normally blocking stream I/O | setRequestProperty replaces; addRequestProperty adds another value |
Set connect and read timeouts; inspect status and error streams | Setup properties must be set before connection |
| Third-party client | Depends on the library and version | Depends on the library | Method names vary; Apache APIs commonly distinguish set/replace from add | Library-specific | Broader features, plus a dependency and version policy |
For new code, start with the JDK client unless your application already standardizes on another library. It has no extra dependency and supports both blocking and asynchronous requests.
Java 11+ HttpClient: add a header to a GET request
Complete synchronous example
This class sends a GET request with a request ID and an Accept header, then prints the status and response body.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
public class CustomHeaderGet {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.example.com/items"))
.timeout(Duration.ofSeconds(20))
.header("X-Request-ID", "abc-123")
.header("Accept", "application/json")
.GET()
.build();
HttpResponse<String> response = client.send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println("HTTP " + response.statusCode());
System.out.println(response.body());
}
}Compile and run it with a Java 11-or-newer JDK. Replace the example URL with an endpoint you are authorized to call. HttpClient is configured separately, while headers belong to the request builder, so request-specific values remain visible and testable.
POST JSON with authorization and content type
Set headers on the same builder before choosing the body publisher. The content type describes the body you are sending; authorization must use the scheme required by the API.
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class CustomHeaderPost {
public static void main(String[] args) throws Exception {
String token = System.getenv("API_TOKEN");
String json = "{"name":"Ada"}";
HttpRequest request = HttpRequest.newBuilder(
URI.create("https://api.example.com/items"))
.header("Authorization", "Bearer " + token)
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(json))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(
request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.statusCode());
System.out.println(response.body());
}
}Do not hard-code a bearer token in source control. Supplying a null or malformed token can produce an invalid authorization value; validate required secrets before building the request.
header, setHeader, and multiple values
header(name, value)adds a value. Use it when repeated field instances are intentional and the target API accepts them.setHeader(name, value)replaces values already set for that name. It is the safer choice for a single effective value, especially when a common request policy can be overridden for one call.headers(name, value, ...)accepts alternating names and values when setting several fields in one call.
Do not manually set protocol-controlled fields such as Content-Length when the client can calculate them from the body publisher. Let the API manage fields it owns. Invalid names, invalid values, or fields restricted by the implementation can raise IllegalArgumentException.
Rank #2
Asynchronous sending
Use sendAsync when a calling thread should not block while the request is in flight. The header setup is identical; only the send operation and result handling change.
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.example.com/items"))
.header("X-Request-ID", "abc-123")
.GET()
.build();
client.sendAsync(request, HttpResponse.BodyHandlers.ofString())
.thenAccept(response -> {
System.out.println(response.statusCode());
System.out.println(response.body());
})
.exceptionally(error -> {
error.printStackTrace();
return null;
});The returned future completes with an HTTP response even for many non-2xx statuses, so your application must check statusCode(). Network failures, timeout expiration, and other transport problems are reported as exceptions or exceptional future completion.
HttpURLConnection for Java 8-era code
Complete GET example
URLConnection has a setup phase followed by connection. Set every request property and timeout before calling connect, getInputStream, getOutputStream, or another method that may connect implicitly.
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.HttpURLConnection;
import java.net.URI;
import java.nio.charset.StandardCharsets;
public class LegacyHeaderGet {
public static void main(String[] args) throws Exception {
HttpURLConnection connection = (HttpURLConnection)
URI.create("https://api.example.com/items")
.toURL().openConnection();
connection.setRequestMethod("GET");
connection.setRequestProperty("X-Request-ID", "abc-123");
connection.setRequestProperty("Accept", "application/json");
connection.setConnectTimeout(10_000);
connection.setReadTimeout(10_000);
int status = connection.getResponseCode();
InputStream stream = status >= 400
? connection.getErrorStream()
: connection.getInputStream();
if (stream != null) {
try (BufferedReader reader = new BufferedReader(
new InputStreamReader(stream, StandardCharsets.UTF_8))) {
reader.lines().forEach(System.out::println);
}
}
connection.disconnect();
}
}setRequestProperty replaces the value for a property. Call addRequestProperty only when sending multiple instances is valid for that endpoint. A server can reject duplicate values even though the client accepted them.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
POST data with a legacy connection
For a request body, enable output, set the method and headers during setup, write the bytes, and then read the response. The exact body format and authorization scheme still come from the target API.
HttpURLConnection connection = (HttpURLConnection)
URI.create("https://api.example.com/items").toURL().openConnection();
connection.setRequestMethod("POST");
connection.setDoOutput(true);
connection.setRequestProperty("Authorization", "Bearer " + token);
connection.setRequestProperty("Content-Type", "application/json");
connection.setConnectTimeout(10_000);
connection.setReadTimeout(20_000);
byte[] payload = "{"name":"Ada"}".
getBytes(java.nio.charset.StandardCharsets.UTF_8);
try (java.io.OutputStream output = connection.getOutputStream()) {
output.write(payload);
}
int status = connection.getResponseCode();Always consume or close the response stream and disconnect when the connection is no longer needed. For substantial new development, migrating to HttpClient usually reduces lifecycle complexity.
Third-party Java clients
Apache HttpClient and similar libraries expose their own request-header APIs and often add pooling, middleware, richer authentication, and other configuration. In Apache’s legacy 3.1 API, setRequestHeader/setHeader replace a value, while addRequestHeader/addHeader add another instance. That 3.1 API is documented as deprecated, so check the exact version in your build before copying method names. Do not mix examples from different major versions; dependency upgrades can change builders, request classes, and timeout configuration.
Header semantics and safe design
Request-specific versus shared policy
Put values such as correlation IDs, per-user authorization, and idempotency keys on the request being sent. If every call in a client has the same policy, centralize construction in a wrapper or request factory. This keeps defaults explicit while allowing a request-specific override with setHeader.
Free tools Windows power users keep installed
One-click scans. No signup required.
Rank #4
Authentication, cookies, and sensitive fields
Follow the service’s documented authentication and cookie mechanism instead of inventing a header name. Never log bearer tokens, API keys, session cookies, or equivalent secrets. Redact header values in HTTP traces and exception reports, and restrict who can read environment variables or secret stores.
Protocol-owned fields
Some fields are calculated or controlled by the HTTP implementation. Supplying a conflicting value can produce malformed requests or failures. In particular, let the JDK client calculate Content-Length from the body publisher, and let the server/client negotiate transport details rather than forcing implementation-managed fields.
Timeouts, status handling, and reliability
- Set a connect timeout on
HttpClient.Builderand a per-request timeout onHttpRequest.Builderwhen a call must have a deadline. - With
HttpURLConnection, set both connect and read timeouts before connection. - Check the returned status code and response body. A request that successfully left the JVM can still receive a 4xx or 5xx response.
- Retry only operations that are safe to repeat, and use an idempotency mechanism required by the API for non-idempotent operations.
- Reuse a configured
HttpClientwhere practical instead of constructing one for every request; keep per-call headers on each request.
Connection failures, DNS problems, TLS errors, timeouts, and malformed requests are different failure classes. Record a request ID (without secrets) and the status or exception category so operators can distinguish server rejection from transport failure.
Troubleshooting custom headers
The server says the header is missing
- Verify that the header was added to the exact request object passed to
sendorsendAsync. - For
HttpURLConnection, move everysetRequestPropertycall beforegetResponseCode,getInputStream, or another implicit connection operation. - Confirm the endpoint, redirect behavior, and authentication requirements. A different host or route may not receive the field you expected.
- Inspect a controlled server-side request log or a redacted wire trace; printing the local builder is not proof that the server accepted or used the value.
IllegalArgumentException while building an HttpRequest
Check the field name and value for invalid characters, empty or malformed input, and implementation-restricted fields. Remove protocol-owned headers and let the client calculate them. Validate user-provided values before passing them to the builder.
Recommended Free Tools
Best Value
Duplicate or conflicting values
Decide whether the endpoint defines a list-valued field. If it expects one value, use setHeader or setRequestProperty and ensure an earlier default is not still present. Use header or addRequestProperty only when repeated instances are intentional.
Timeouts or empty error details
Set explicit connect/read or request deadlines, then inspect the status and the error stream. In legacy code, getInputStream() can throw for an error response; read getErrorStream() when the status is 400 or higher. In asynchronous code, attach an exceptional completion handler so transport failures are not silently discarded.
Or skip the browser setup
If the task that led you here is obtaining a clean screenshot rather than implementing a browser yourself, ScreenshotNeo provides a single HTTP endpoint. The request below returns a WebP screenshot of the target URL; the complete API options and response behavior are documented at screenshotneo.com/docs/.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpBefore capture, ScreenshotNeo accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response identifies the page verdict and billing status with X-Page-Verdict and X-Billed headers. It also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account to get started.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →FAQ
Are HTTP header names case-sensitive?
No. HTTP field names are case-insensitive, although values and the server’s documented spelling or format can still matter. Use the exact name shown by the API documentation for readability.
Frequently Asked Questions
Are HTTP header names case-sensitive?
No. HTTP field names are case-insensitive, although values and the server’s documented spelling or format can still matter. Use the exact documented name for readability.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
