Retry-After

사용법

Retry-After 헤더는 서버가 클라이언트에게 재시도 전 대기를 요구해야 하는 응답에 나타납니다. 이 헤더는 보통 세 가지 상태 코드와 함께 사용됩니다.

이 헤더는 두 가지 형식을 받습니다. 초 단위 지연(delta-seconds) 또는 절대적인 HTTP-date입니다. 초를 사용할 때 값은 대기할 초 수를 나타내는 음수가 아닌 정수입니다. HTTP-date를 사용할 때 값은 IMF-fixdate 형식을 따릅니다.

예의 바른 클라이언트와 크롤러는 복구 중인 서버에 과부하를 주지 않기 위해 이 헤더를 준수합니다.

참고

검색 엔진 크롤러는 503 응답의 Retry-After를 페이지를 색인에서 제거하라는 뜻이 아니라 나중에 해당 URL을 다시 방문하라는 신호로 취급합니다. Googlebot과 Bingbot 모두 이 헤더를 존중하여 재방문 일정을 잡습니다. 계획된 점검 중에 Retry-After와 함께 503 Service Unavailable을 반환하면 색인 가능성이 유지됩니다. 이 헤더가 없으면 장기간의 다운타임은 색인 해제 위험을 초래합니다.

Delta-seconds

클라이언트가 요청을 재시도하기 전에 대기해야 하는 초 수를 지정하는 음수가 아닌 정수입니다.

Retry-After: 120

HTTP-date

그 이후에는 클라이언트가 자유롭게 재시도할 수 있는 IMF-fixdate 형식의 절대 날짜와 시각입니다. 날짜는 GMT를 사용하며 Day, DD Mon YYYY HH:MM:SS GMT 형식을 따릅니다.

Retry-After: Sat, 31 Oct 2026 18:00:00 GMT

예시

점검 시간대에 503으로 응답하는 서버가 클라이언트에게 재시도 전 3600초(1시간) 대기하라고 알립니다.

HTTP/1.1 503 Service Unavailable
Retry-After: 3600

429로 응답하는 API 레이트 리미터가 제한이 재설정되는 절대 날짜를 제공합니다. 클라이언트는 지정된 시각까지 요청을 중단합니다.

HTTP/1.1 429 Too Many Requests
Retry-After: Sat, 31 Oct 2026 12:30:00 GMT

301과 함께 예정된 리다이렉트에 지연을 포함시켜 여러 클라이언트가 즉시 재시도하며 몰리는 상황을 방지합니다.

HTTP/1.1 301 Moved Permanently
Location: https://new.example.re/resource
Retry-After: 60

참고

API 레이트 리미터는 Retry-After를 RateLimit-Limit 헤더와 함께 제공하는 경우가 많습니다. RateLimit-Remaining 헤더는 현재 윈도에 남은 요청 수를 보여 주고, Retry-After는 429 응답 이후 정확히 언제 재개하면 되는지 클라이언트에 알려 줍니다. 잘 설계된 API는 둘 다 포함시켜 클라이언트가 제한된 엔드포인트를 두드려 대는 대신 우아하게 백오프하도록 합니다.