Expectation Failed

Description

Examples

POST /api/uploads HTTP/1.1
Host: api.example.com
Content-Type: application/octet-stream
Content-Length: 52428800
Expect: 100-continue
Authorization: Bearer token123

HTTP/1.1 417 Expectation Failed
Content-Type: application/json
Content-Length: 128 
{"error": "expectation_failed", "message": "This server does not support the Expect: 100-continue mechanism. Resend without the Expect header."}

PUT /api/documents/99 HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 4096
Expect: 200-ok
Authorization: Bearer token456

{"title": "Updated Document", "body": "..."}

HTTP/1.1 417 Expectation Failed
Content-Type: application/json

{"error": "expectation_failed", "message": "The Expect header value '200-ok' is not supported. Only '100-continue' is recognized.", "supported_expectations": ["100-continue"]}

POST /api/data/ingest HTTP/1.1
Host: api.example.com
Content-Type: text/csv
Content-Length: 10485760
Expect: 100-continue
X-Request-ID: req_abc123

HTTP/1.1 417 Expectation Failed
Content-Type: application/json
Via: 1.1 proxy.internal.net

{"error": "expectation_failed", "message": "The intermediary proxy cannot forward the Expect header to the origin server. Please retry without the Expect header.", "proxy": "proxy.internal.net"}

Edge Cases

• •curl sends Expect: 100-continue automatically for POST/PUT bodies larger than 1024 bytes. If a server returns 417, curl retries without the header — this can cause double requests and confusing logs.
• •Some reverse proxies (older nginx, HAProxy configurations) strip the Expect header before forwarding, then return 417 if the backend requires the 100-continue handshake. The fix is proxy-level configuration, not client-side.
• •HTTP/2 and HTTP/3 do not use the Expect: 100-continue mechanism — it's a purely HTTP/1.1 concept. Clients should never send Expect headers over h2/h3 connections.
• •A server that returns 417 MUST NOT have already sent a 100 Continue response for the same request. If it sent 100, it committed to accepting the body — 417 after 100 is a protocol violation.
• •Some servers return 417 when the Content-Length exceeds their configured maximum, using it as an early rejection before body transmission. Technically 413 Payload Too Large is more appropriate, but 417 is used because the rejection happens during the expect negotiation phase.
• •Load balancers that buffer requests may absorb the Expect header and never forward it, making the 100-continue mechanism invisible to the backend. The client receives 200 directly, not 100 then 200.
• •AWS API Gateway and some cloud proxies do not support Expect: 100-continue and may return 417 or silently ignore the header. SDKs that rely on the mechanism need workarounds for these environments.

When You'll See This

• →curl sending a large POST body hits a server that doesn't support 100-continue
• →An HTTP client library sends Expect: 100-continue through a proxy that strips it
• →A file upload service rejects the request early because authentication failed during the expect phase
• →A client sends a non-standard Expect header value the server doesn't recognize
• →Legacy Java HttpURLConnection sends Expect: 100-continue to a modern serverless endpoint that doesn't implement it
• →An IoT device with limited bandwidth uses 100-continue to avoid sending payloads that will be rejected, but the gateway doesn't support it
• →A batch import client sends Expect: 100-continue for a 50MB CSV upload, and the server's max body size is 10MB

Implementation References

History

Introduced in HTTP/1.1 (RFC 2068, January 1997) alongside the Expect header mechanism. Refined in RFC 2616 (June 1999) which clarified proxy behavior. Consolidated in RFC 9110 (June 2022, §15.5.18) as part of the HTTP semantics specification rewrite. The status code remains active but is increasingly irrelevant as HTTP/2 and HTTP/3 deprecate the 100-continue mechanism entirely.

Related Status Codes

Related Headers

FAQ