개요

Retry-After는 클라이언트가 언제 다시 요청을 시도해도 되는지를 알려주는 응답 헤더입니다. 서버 과부하·점검(503)이나 속도 제한 초과(429) 상황에서 무분별한 재시도를 막고 회복 시간을 확보하는 데 씁니다.

값은 대기할 초(정수)이거나, 재시도 가능해지는 절대 시각(HTTP-date) 두 형식 중 하나입니다.

자세히

429 Too Many Requests와 함께 쓰면 클라이언트에게 다음 요청까지 얼마나 기다려야 하는지 명시적으로 알려줍니다. 잘 만든 클라이언트·SDK는 이 값을 읽어 자동 백오프에 반영하므로, 서버 부하를 실질적으로 줄일 수 있습니다.

503 Service Unavailable(점검·과부하)에서 Retry-After를 주면 크롤러·모니터링·클라이언트가 그 시간 동안 조용히 기다리게 유도할 수 있습니다. 계획된 점검이면 절대 시각(HTTP-date), 부하 기반이면 상대 초를 쓰는 편이 자연스럽습니다.

일부 리다이렉트(3xx)에서도 잠시 후 이동을 지시하는 용도로 쓸 수 있으나, 실무에서 압도적으로 흔한 사용처는 429·503입니다.

문법

Retry-After: <HTTP-date> | <seconds>

e.g. Retry-After: 120

실무 참고

• 클라이언트는 서버가 준 값을 존중하되, 여러 요청이 동시에 같은 시각에 재시도해 몰리는 것(thundering herd)을 막기 위해 약간의 지터(무작위 오프셋)를 더하는 것이 좋습니다.
• 값을 신뢰할 수 없거나 지나치게 크면 클라이언트가 무시할 수 있으므로, 합리적 범위의 값을 주세요.
• 표준 Retry-After 외에 X-RateLimit-* 계열 헤더로 남은 할당량·리셋 시각을 함께 제공하면 클라이언트의 백오프 정확도가 올라갑니다.

관련 헤더

관련 상태코드

스펙 근거