417 Expectation Failed 해결

Problem

꽤 큰 본문을 담은 POST나 PUT를 보냈는데, 기대한 응답 대신 417 Expectation Failed가 돌아옵니다. 본문은 멀쩡합니다. 엔드포인트는 브라우저에서 잘 됩니다. 그런데 curl·라이브러리·스크립트 업로드 같은 여러분의 클라이언트만 계속 튕깁니다. 서버는 여러분이 보낸 것에 이의를 제기하는 게 아닙니다. 보내기 전에 클라이언트가 던진 질문에 이의를 제기하는 것입니다.

Symptoms

• POST/PUT/PATCH가 애플리케이션 오류 본문 없이 즉시 417을 반환합니다.
• 큰 요청에서만 발생합니다 — 같은 엔드포인트에 작은 요청은 잘 됩니다.
• 실패하는 요청에 Expect: 100-continue 헤더가 실려 있습니다.
• 브라우저나 다른 HTTP 클라이언트에서는 되는데 curl이나 특정 라이브러리에서만 실패합니다.
• 경로에 새 프록시·로드밸런서·사내 네트워크가 끼어든 뒤 시작됐습니다.

What This Error Actually Means

HTTP/1.1에는 큰 업로드를 위한 예의 장치가 있습니다. 큰 본문을 네트워크로 밀어보내기 전에, 클라이언트는 헤더에 Expect: 100-continue를 붙여 보내고 기다립니다. 서버는 헤더 — 인증, 콘텐츠 타입, 선언된 크기 — 를 보고, 본문을 받을 의향이 있으면 100 Continue로, 어차피 거절할 거면 최종 상태(401, 413 등)로 답합니다. 클라이언트는 어차피 거절당할 서버에 수 메가바이트를 밀어붙이는 낭비를 피합니다.

100-continue는 표준이 정의한 유일한 기대입니다. 그리고 417은 그 체인이 이 기대를 존중하지 못할 때 받는 응답입니다. RFC 9110 §15.5.18은 정확합니다: 417은 기대가 “inbound 서버 중 최소 하나에 의해 충족되지 못한 것”입니다. 반드시 오리진이 아니라 — 경로 상의 최소 한 서버입니다. 흔한 범인은 이 메커니즘보다 오래된 HTTP/1.0 홉입니다. 이해하지 못하는 헤더를 보면 무시하는 대신 요청을 통째로 거부합니다.

핵심 단어는 inbound입니다. 여러분의 본문은 애플리케이션에 도달조차 못 했습니다. 요청은 Expect 헤더 하나 때문에 핸드셰이크 단계에서, 클라이언트와 서버 사이 어딘가에서 죽었습니다. RFC는 처방도 직접 건넵니다: 417을 받은 클라이언트는 “100-continue 기대 없이 요청을 재전송해야 한다(SHOULD).” 헤더를 떼고 재전송하면 똑같은 본문이 통과합니다 — 애초에 본문에는 문제가 없었으니까요.

Top 3 Causes

1. 경로 상의 레거시 HTTP/1.0 프록시·로드밸런서 - 교과서적 원인입니다. Expect: 100-continue는 HTTP/1.1 기능이고, 기대를 구현하지 않은 HTTP/1.0 중간자는 헤더를 무시해야 하지만, 낡은 미들박스 상당수는 대신 417로 거부합니다. 단서: 오리진 직접 연결은 되고 특정 프록시·사내 네트워크를 지날 때만 실패합니다.
2. 클라이언트가 Expect: 100-continue를 자동으로 붙였는데 상류의 뭔가가 싫어함 - 많은 HTTP 클라이언트가 본문이 충분히 크면 알아서 헤더를 붙입니다 — libcurl은 대략 1024바이트를 넘는 본문에 붙입니다. 여러분이 핸드셰이크를 요청한 게 아니라 라이브러리가 한 것입니다. 서버 앞의 어느 홉이 이 춤을 못 추면, 큰 업로드는 전부 417이고 작은 요청만 성공합니다. 큰 요청만 헤더를 유발했으니까요.
3. 기대를 거부하도록 설정된 엄격한 서버·WAF - 일부 오리진과 웹 애플리케이션 방화벽은 Expect: 100-continue에 응답하는 대신 아예 거부하도록 설정돼 있습니다 — 의도적일 때도, 옛 설정의 부작용일 때도 있습니다. 요청은 정상인데 정책이 100-continue 게임을 하지 않을 뿐이고, 417이 그 거절의 표현입니다.

Diagnose with DechoNet

• HTTP 검사로 엔드포인트 자체가 Expect 헤더 없는 일반 요청에 깨끗이 응답하는지 확인하세요. 도구는 정상 응답을 받는데 여러분의 클라이언트만 417을 받는다면, 문제를 서버나 페이로드가 아니라 그 기대로 좁힌 것입니다.
• 검사는 응답 헤더와 중간자 지문(Via, Server, 프록시 시그니처)을 드러냅니다. 특정 엣지 뒤에서만 나는 417은 경로 상의 미들박스를 정확히 가리킵니다 — 고치거나 우회할 대상은 여러분의 코드가 아니라 그것입니다.

Resolution Checklist

• 정말 417이 맞는지 확인 — 400(형식 오류)이나 413(본문 초과)이 아닌지. 417만 Expect 헤더 문제이고, 417만 요청을 뜯어고치는 게 아니라 제거로 풀립니다.
• 기대 없이 재전송. curl이라면 -H "Expect:"(빈 값)로 헤더를 통째로 떼세요. 같은 본문이 한 번에 업로드됩니다.
• HTTP 라이브러리의 auto-expect 끄기. 대부분의 클라이언트에 큰 본문의 자동 Expect: 100-continue를 끄는 설정이 있습니다 — 끄거나, 빈 Expect 헤더를 직접 보내세요.
• 거슬리는 홉 찾기. 프록시·로드밸런서·사내 네트워크를 지날 때만 실패하면 그 중간자가 기대를 거부하는 것입니다. 오리진 직접 연결로 증명한 뒤 미들박스를 고치거나 우회하세요.
• 서버·WAF를 운영한다면 Expect 헤더를 거부하도록 설정돼 있는지 확인하고, 요청을 튕기는 대신 100 Continue로 답할지 결정하세요.
• 같은 경로로 재검증. 깨끗한 직접 연결이 아니라 실제 네트워크 경로로 수정을 검증하세요 — 실패가 경로에 있었다는 게 요점입니다.

When to Escalate

• Expect 헤더를 뗐는데도 417이 계속되면 서비스 앞단의 프록시·로드밸런서·WAF 운영자에게 에스컬레이션하세요 — 미들박스가 자체 기대를 주입하거나, 그쪽 로그에만 보이는 방식으로 요청을 재작성하고 있을 수 있습니다.
• 서드파티 API가 여러분이 올바로 보낸 문서화된 업로드에 417을 반환하면 알리세요: 큰 업로드를 광고하는 엔드포인트의 417은 대개 그쪽 경로의 깨진 HTTP/1.0 홉을 뜻하며, 그 중간자는 그들만 고칠 수 있습니다.