ESP32 HTTPClient returns a negative code: -1, -11 and what they mean

A negative code from HTTPClient means the request failed before a normal reply arrived. Print the code and the text from errorToString.

What the message means

Positive codes such as 200 and 404 come from the server. Negative codes come from the client library and show a network problem.

Fix it in this order

1. Print http.errorToString(code) next to the number.
2. Code -1 is connection refused. Check the address, the port and that the server is running.
3. Code -11 is a read timeout. Increase the timeout, or check that the server answers.
4. Check that Wi-Fi is connected before you call the request.
5. For https addresses give the client a root certificate. Use insecure mode only for testing on your own network.
6. Open the same address in a browser on the same network to confirm it works.

Why it happens

A negative number from HTTPClient is a client-side error, not an HTTP status. Common ones are -1 for connection refused, -4 for not connected, -5 for connection lost and -11 for a read timeout. The server was never reached or did not answer.

Print the text with http.errorToString(code), check the URL and port, confirm the board has a Wi-Fi connection, and for https check certificate handling and free memory.

If you see this, do this

Related

Wi-Fi will not connect, web server not reachable.

Last reviewed: November 2026. These are the usual causes and the order that finds them fastest. Test on your own board; clones and cables differ.

Why this happens

HTTPClient on the ESP32 returns a positive number when the server answered, which is the normal HTTP status such as 200 or 404. A negative number does not come from the server; it is the library telling you that something failed before a proper answer arrived: the TCP connection, sending the request, reading the reply, or a timeout. The library has a function, errorToString, that turns the code into text.

So a negative code tells you where to look: Wi-Fi and address, server reachability, TLS settings for https, memory, or timeouts. It is not a failure of the server’s application.

How to confirm the cause

• Print WiFi.status() == WL_CONNECTED and WiFi.localIP() before the request. If not connected, nothing else matters yet.
• Print http.errorToString(code) to get the name of the failure instead of a bare number.
• Try the same address from a computer on the same network. If it fails there, the server or the address is wrong.
• Print ESP.getFreeHeap() before the call. TLS uses a lot of RAM, and very low free memory gives failures.
• Check that you used http or https to match the server; a plain request to a TLS port ends in a broken read.

Worked example

A request that prints the cause on failure and sets a longer timeout.

HTTPClient http;
http.setTimeout(10000);              // ms
http.begin(url);
int code = http.GET();
if (code > 0) {
  Serial.printf("HTTP %d\n", code);
} else {
  Serial.printf("failed: %s\n", http.errorToString(code).c_str());
}
http.end();

Common mistakes

• Reading the response body when the code is negative.
• Forgetting http.end(), so sockets and memory build up.
• Using https with no certificate or test setting and wondering why the connection is refused.
• Ignoring redirects, which return 301 or 302 and need following.
• Starting the request before Wi-Fi finished connecting.

If this did not fix it

• The device clock is wrong, so certificate checks fail on https.
• DNS fails; try the server’s numeric address as a test.
• The server closes idle connections; reconnect before each request.
• Power dips during radio use cause a dropped connection.