자동 재시도 (Automatic Retries)
자동 재시도 (Automatic Retries)
LLM API는 순간적인 속도 제한(429)이나 서버 오류(5xx)로 자주 실패해요. 매번 손으로 재시도 로직을 짜는 대신, Portkey 게이트웨이가 지수 백오프(exponential backoff) 로 실패한 요청을 자동 재시도해 줘요. 최대 5번까지 시도하고, 특정 에러 코드에서만 재시도하도록도 지정할 수 있어요.
기본 예시
attempts로 재시도 횟수를 정해요.
{
"retry": { "attempts": 5 },
"override_params": { "model": "@openai-prod/gpt-4o" }
}
특정 에러 코드에서만 재시도하고 싶다면 on_status_codes를 써요.
{
"retry": { "attempts": 3, "on_status_codes": [429, 503] },
"override_params": { "model": "@openai-prod/gpt-4o" }
}
on_status_codes를 지정하면 그 코드에서만 재시도하고, 기본 코드는 쓰지 않아요.
기본 재시도 코드
기본 값은 [429, 500, 502, 503, 504, 529]이에요.
프로바이더 재시도 헤더 존중하기
use_retry_after_headers: true로 두면 프로바이더가 돌려주는 retry-after-ms, x-ms-retry-after-ms, retry-after 헤더 값을 대기 시간으로 써요. 지수 백오프 대신 이 값으로 다음 재시도 시점을 정하는 거죠.
{
"retry": { "attempts": 3, "on_status_codes": [429], "use_retry_after_headers": true },
"override_params": { "model": "@openai-prod/gpt-4o" }
}
프로바이더가 이런 헤더를 주지 않으면 다시 표준 지수 백오프로 돌아가요. 단일 요청의 누적 재시도 대기 시간은 60초로 제한되며, 60초를 넘는 단일 Retry-After 값이 있으면 바로 실패 처리돼요.
지수 백오프 일정
| 시도 | 대기 시간 |
|---|---|
| 최초 | 즉시 |
| 1차 재시도 | 1초 |
| 2차 재시도 | 2초 |
| 3차 재시도 | 4초 |
| 4차 재시도 | 8초 |
| 5차 재시도 | 16초 |
재시도 시도 헤더
응답의 x-portkey-retry-attempt-count 헤더로 재시도 상황을 알 수 있어요.
| 값 | 의미 |
|---|---|
-1 |
모든 재시도 소진, 요청 실패 |
0 |
재시도 미설정 |
>0 |
해당 재시도 시도에서 성공 |
참고로 재시도 시도는 개별로 로그되지 않고 응답 시간이 하나의 로그 항목에 합산돼요.