# 417 Expectation Failed

> https://http-status.org/docs/417

**Family:** 4xx Client Error

## Rationale

The expectation given in the Expect header could not be met.

## In Plain Terms

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

## Description

The HTTP 417 Expectation Failed status code indicates that the expectation given in the request's Expect header field could not be met by the server.

## Server Perspective

### Usage
- 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

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

### Common Headers
- Expect

### Body
- Optionally explain which expectation could not be honored.

### 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)

## Client Perspective

### Pitfalls
- Do not confuse 417 with a generic upload or validation error

## Examples

### Unsupported 100-continue expectation

Server cannot provide 100-continue response for this endpoint

**Request:**
```
POST https://api.example.test/api/upload
Expect: 100-continue
```

**Response:**
```
417 Expectation Failed
Content-Type: application/json

{
  "error": "expectation_failed"
}
```

## Related Codes

- [400 Bad Request](/docs/400.md)
- [100 Continue](/docs/100.md)