재시도 가능한 HTTP 상태 코드: 어떤 오류를 재시도해야 하나요?

실패가 일시적일 가능성이 높을 때 요청을 재시도하세요. 응답이 아예 없는 경우(타임아웃이나 끊긴 연결), 408 Request Timeout, 429 Too Many Requests, 그리고 500, 502, 503, 504 같은 5xx 서버 오류가 여기에 해당합니다. 그 밖의 4xx 오류는 대부분 요청 자체가 잘못됐다는 뜻이므로 재시도하지 마세요. 같은 요청에는 같은 응답이 돌아옵니다. POST는 멱등성 키가 있을 때만 재시도하세요. 그래야 다시 보내도 작업이 두 번 실행되지 않습니다.

상태 코드 정의는 RFC 9110과 RFC 6585에서 인용했고, 2026-09-28에 확인했습니다. Sume 예시는 오류와 비용 (영문), 실행 기다리기 (영문), Format 호출하기 (영문) 문서, 그리고 따로 표시한 곳은 현재 API 코드에서 가져왔습니다.

어떤 HTTP 상태 코드를 재시도해야 하나요?

잠시 뒤에 같은 요청이 성공할 수 있는 코드입니다. RFC 9110의 상태 코드 분류가 방향을 알려 줍니다. 4xx는 클라이언트가 잘못한 것으로 보인다는 뜻이고, 5xx는 서버가 잘못했거나 요청을 수행할 수 없다는 뜻입니다. Sume의 TypeScript SDK도 같은 곳에 선을 긋습니다. 408, 429, 5xx, 그리고 전송 실패를 재시도합니다.

POST를 재시도해도 안전한가요?

다시 보내도 작업이 두 번 실행될 수 없을 때만 안전합니다. RFC 9110은 클라이언트가 POST 같은 멱등하지 않은 요청을, 그 요청이 실제로 멱등하다는 것을 알지 못하는 한 자동으로 재시도하지 않아야 한다고 말합니다. 멱등성 키는 API가 POST를 안전하게 다시 보낼 수 있게 만드는 방법입니다. Sume에서는 같은 Idempotency-Key와 같은 본문을 보내면 두 번째 Job이나 실행을 만드는 대신 원래 Job이나 실행이 돌아옵니다. 메서드 규칙은 POST는 멱등한가요?에서, 키 설계는 AI 영상 API 멱등성 키에서 다룹니다.

상태 코드만 보면 언제 잘못 판단하게 되나요?

오류 본문이 다르게 말할 때입니다. RFC 9110은 서버가 4xx나 5xx 응답에 상황을 설명하고, 그 상황이 일시적인지 영구적인지도 밝히도록 요청합니다. Sume의 오류 본문은 retryable과 retry_after_seconds로 이를 알려 주는데, 각각 같은 요청을 다시 보내면 성공할 수 있는지와 먼저 얼마나 기다려야 하는지를 나타냅니다. 다음은 플래그와 상태 코드 규칙이 어긋나는 네 가지 경우입니다. 마지막 경우에는 플래그보다 Job 상태를 믿으세요.

• 502 attachment_fetch_failed: Sume가 첨부 URL을 가져오지 못했습니다. 5xx이지만 원인은 입력에 있으며 next_action: fix_input이 붙으므로, 재시도하는 대신 URL을 공개적으로 접근할 수 있게 만드세요.
• 503 provider_not_configured: 그 런타임에서 프로바이더 실행을 쓸 수 없습니다. 문서는 공격적으로 재시도하지 말라고 하며, 현재 코드는 이 오류를 retryable: false로 표시합니다.
• 409 idempotency_key_in_use: 같은 키를 쓴 다른 요청이 처리 중입니다. retryable: true이므로 일 초쯤 기다렸다가 다시 보내세요.
• GET /v1/jobs/{id}/result의 409 job_not_completed: 현재 코드에서는 Job이 실패했거나 취소됐을 때도 재시도 가능으로 표시되므로, Job 상태가 종료 상태가 될 때까지 폴링하세요. 다른 충돌은 409 Conflict 오류에서 다룹니다.

500 오류는 재시도해야 하나요?

네, 반복해도 안전한 요청이라면 백오프를 두고 정해진 횟수만큼 재시도하세요. 현재 코드에서 Sume는 예기치 않은 500을 retryable: true, next_action: contact_support로 표시합니다. 재시도하고, 계속 실패하면 지원팀에 request_id를 알려 주세요.

Sume 실행을 폴링하는 동안에는 문서가 429나 503도 일시적인 오류로 봅니다. 폴링 루프를 중단해도 실행과 그에 따른 지출은 멈추지 않으므로, 백오프한 뒤 다시 폴링하세요.

재시도 사이에는 얼마나 기다려야 하나요?

응답에 Retry-After가 있으면 그 값을 쓰고, 없으면 지터를 더한 지수 백오프를 쓰세요. Sume SDK는 기본적으로 둘 다 하며, 재시도는 두 번입니다. 이 헤더의 두 가지 형식과 429가 얼마나 지속되는지는 Retry-After 헤더에서 설명합니다.