417 Expectation Failed

Description

The 417 Expectation Failed status code indicates that the server cannot meet the requirements of the Expect request-header field. This status code is typically returned when a client includes an Expect: 100-continue header in its request, but the server determines it cannot satisfy the expectation or doesn't support this header field.

This status code is commonly used when: - A client uses the Expect header with a value the server doesn't recognize or support - A server knows in advance it cannot fulfill the expectation specified in the Expect header - A proxy or intermediary determines that the expectation is unlikely to be met by the origin server

The 417 Expectation Failed status helps clients understand that their request contains an expectation that cannot be satisfied, allowing them to modify their request or proceed differently.

Syntax

The server responds with a 417 Expectation Failed status:

HTTP/1.1 417 Expectation Failed
Content-Type: application/json
Content-Length: [length in bytes]

{
  "error": "Expectation Failed",
  "message": "The server cannot meet the requirements in the Expect header field"
}

Examples

Unsupported Expectation Example

A client includes an Expect header with a value the server doesn't support:

Client Request:

POST /api/upload HTTP/1.1
Host: api.example.com
Content-Type: application/octet-stream
Content-Length: 15000000
Expect: 100-continue

Server Response:

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

{
  "error": "Expectation Failed",
  "message": "This server does not support the Expect: 100-continue header",
  "suggestion": "Please upload your file without the Expect header"
}

Custom Expectation Example

A client uses a custom expectation value that the server doesn't recognize:

Client Request:

PUT /documents/report.docx HTTP/1.1
Host: docs.example.com
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Length: 2500000
Expect: custom-validation-protocol
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response:

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

{
  "error": "Expectation Failed",
  "message": "The server does not recognize or support the 'custom-validation-protocol' expectation",
  "supported_expectations": ["100-continue"]
}

Conditional Expectation Example

A client includes an Expect: 100-continue header, but the server knows it will reject the request:

Client Request:

POST /api/videos HTTP/1.1
Host: media.example.com
Content-Type: video/mp4
Content-Length: 1073741824
Expect: 100-continue
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Server Response:

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

{
  "error": "Expectation Failed",
  "message": "The server cannot accept a file of this size",
  "max_file_size": 524288000,
  "your_file_size": 1073741824,
  "suggestion": "Please reduce the file size or use our chunked upload API"
}

Summary

The 417 Expectation Failed status code is a specific response for handling issues with the HTTP Expect header field. It allows servers to quickly inform clients when they cannot meet the expectations set in the request, without requiring the client to send the entire request body. This is particularly useful for large uploads or operations where the server can determine in advance that the request will not succeed. By providing this early feedback, the 417 status code helps conserve bandwidth and improve efficiency in HTTP communications.