Expectation Failed

4xx Client Error

Back to list.md

ELI5

You told me to expect something specific to happen, but I can't make that happen the way you want.

Server perspective

Use 417 when the expectation in the Expect header cannot be met.

When to use

•Return 417 when the server cannot honor an Expect value such as 100-continue
•Use it when the request depends on an explicit expectation the server will not satisfy
•Server cannot satisfy Expect: 100-continue
•Custom expectation headers cannot be met
•Server doesn't support expected behavior
•Expectation conflicts with server capabilities

How to respond

•Explain which expectation failed when that helps the client recover
•Support 100-continue where practical if large-body clients depend on it

Headers to consider

•Expect

Response body

•Optionally explain which expectation could not be honored.

Server-side pitfalls

•Do not use 417 for generic business or validation failures
•Do not require Expect unnecessarily when normal requests would work fine without it
•When the Expect header value is malformed or unrecognized (use 400 Bad Request for bad syntax)
•General request conflicts (use 409 Conflict)
•Authentication issues (use 401 Unauthorized)

Examples

Unsupported 100-continue expectation

Request:

POST https://api.example.test/api/upload

# Headers
Expect: 100-continue

Response:

417 Expectation Failed

# Headers
Content-Type: application/json

# Body
{
  "error": "expectation_failed"
}

Server cannot provide 100-continue response for this endpoint

References

Related Status Codes

400

Bad Request

Your request doesn't make sense or has mistakes in it. Check what you're sending and try again.

100

Continue

Imagine calling ahead before mailing a very heavy package: 'Can you accept this?' The post office says yes, so you drive it over. That's 100 Continue — the server greenlit the request headers, so send the rest of the data.