Skip to main content
4xx Client Error

417 Expectation Failed

The server cannot meet the requirements of the Expect request-header field.

Meaning & Description

The 417 Expectation Failed status code indicates that the expectation given in the request's `Expect` header field could not be met by at least one of the inbound servers. This is most commonly used in conjunction with the `Expect: 100-continue` header. When a client wants to send a large payload, it can send just the headers first with `Expect: 100-continue`. If the server decides it will reject the request (e.g., due to authentication failure or payload limits), it returns 417, saving the client from uploading the massive body.

Common Causes

  • An HTTP client (like curl or Java HttpURLConnection) automatically appending `Expect: 100-continue` for large POST requests, but encountering a proxy that doesn't support it.
  • A client sending an unknown or unsupported value in the `Expect` header.

How to fix a 417 error

  1. If you control the client, disable the `Expect: 100-continue` header behavior in your HTTP library.
  2. Check if intermediate proxies (Squid, HAProxy) are properly configured to handle HTTP/1.1 Expect headers.
  3. If sending an unknown Expect value, ensure you only use `100-continue`, as no other expectations are defined by HTTP/1.1.

Browser & SEO Behaviour

Browser Behavior

Browsers generally do not use the `Expect: 100-continue` header, so end-users rarely encounter this. It is mostly seen in programmatic API clients.

SEO Impact

No direct SEO impact, as search engines do not send Expect headers.

CDN Behavior

Most modern CDNs handle `Expect: 100-continue` transparently, but legacy network appliances might respond with a 417.

Code Examples

HTTP
HTTP/1.1 417 Expectation Failed
Connection: close
Content-Type: text/plain

Expectation not met.
Node.js (HTTP)
const http = require("http");

const server = http.createServer((req, res) => {
  if (req.headers.expect && req.headers.expect !== "100-continue") {
    res.writeHead(417);
    res.end("Expectation Failed");
  }
});
Python (Requests)
# To avoid 417 errors in requests when dealing with bad proxies, you might need to ensure Expect is not sent.
import requests

headers = {"Expect": ""}
response = requests.post("https://api.example.com/upload", data="large_data", headers=headers)
Go (net/http)
func handler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Expect") != "" && r.Header.Get("Expect") != "100-continue" {
        http.Error(w, "Expectation Failed", http.StatusExpectationFailed)
        return
    }
    w.WriteHeader(http.StatusOK)
}
C# (HttpClient)
// In .NET, HttpClient sends Expect: 100-continue by default for large POSTs.
// To disable it and avoid 417 errors with non-compliant servers:
var client = new HttpClient();
client.DefaultRequestHeaders.ExpectContinue = false;
cURL
# cURL sends Expect: 100-continue automatically for payloads > 1024 bytes.
# To disable it and avoid a 417:
curl -X POST -H "Expect:" -d @largefile.bin https://api.example.com/upload

Raw HTTP Response Example

HTTP Response
HTTP/1.1 417 Expectation Failed
Date: Wed, 21 Oct 2026 07:28:00 GMT
Connection: close

Real-world Examples

Squid Proxy: Older versions of Squid and other legacy proxies sometimes failed to handle HTTP/1.1 Expect headers, resulting in 417 errors.
cURL / libcurl: By default, libcurl adds `Expect: 100-continue` for bodies larger than 1MB. If the server does not support it, it may return a 417.

Frequently Asked Questions

Why does cURL suddenly return a 417 Expectation Failed error?

When posting data larger than 1024 bytes, cURL automatically adds the `Expect: 100-continue` header. If the destination server or proxy does not support it, it returns 417. You can fix this by passing `-H "Expect:"` to clear the header.

What is the purpose of Expect: 100-continue?

It allows a client to check if the server will accept a request based on the headers (like authentication or file size) before wasting bandwidth uploading a massive request body. The server replies with 100 Continue or an error code.

Are there any other Expect headers besides 100-continue?

No. Currently, `100-continue` is the only expectation defined in the HTTP/1.1 specification.

Did You Know?

If a server receives `Expect: 100-continue` and decides to reject the request based on headers (e.g., Bad Credentials), it is usually better to return the specific error (e.g., 401 Unauthorized) rather than a generic 417.

Developer Tips

  • If you are building an API integration and experience random upload failures with 417 errors, explicitly disable `ExpectContinue` in your HTTP client library.
  • When building a server, if you receive an `Expect` header with an unrecognized value, you must respond with a 417.

Interview Questions

These are questions you might face in a backend or API design interview that touch on HTTP 417.

Explain the handshake that occurs with the `Expect: 100-continue` header.

The client sends the request headers including `Expect: 100-continue` and pauses. The server inspects the headers. If acceptable, the server replies with a `100 Continue` status, and the client proceeds to send the body. If unacceptable, the server replies with a 4xx error (or 417), saving the client from uploading the data.

Common Interview Mistakes

  • Assuming a 417 error means a JSON payload was missing expected fields. "Expectation" here refers strictly to the HTTP `Expect` header, not application-level validation expectations.