Skip to main content
Current API의 모든 인증된 POST는 Idempotency-Key 헤더를 받습니다. 키가 포함된 요청이 성공하면 응답이 24시간 동안 저장됩니다. 같은 키로 재시도하면 요청을 다시 실행하는 대신 저장된 응답을 재생합니다. 따라서 시간 초과되거나 내 쪽에서 오류가 발생한 요청을 중복 청구, 이체, 리소스 생성의 위험 없이 안전하게 재시도할 수 있습니다. 최대 255바이트의 고유한 문자열이면 무엇이든 키로 사용할 수 있으며, UUID가 좋은 기본값입니다. 서로 다른 작업마다 새 키를 생성하고, 해당 작업을 재시도할 때만 정확히 같은 키를 재사용하세요.
재생된 응답은 상태 코드를 포함하여 원래 응답과 바이트 단위로 동일하며, Idempotent-Replayed: true 헤더가 포함되어 재생과 새 실행을 구분할 수 있습니다.
오류 응답도 재생됩니다. 원래 요청이 4xx로 실패했다면 같은 키로 재시도해도 동일한 오류가 반환됩니다. 그 실패가 요청의 실제 결과이므로, 대신 수정된 요청과 함께 새 키를 보내세요.
알아두면 좋은 몇 가지 세부 사항:
  • “같은 요청”이란 메서드, 경로, 쿼리 문자열, 본문, Api-Version-Date가 모두 원래 요청과 정확히 일치하는 것을 의미합니다. 차이가 있으면 키 재사용으로 간주되어 error.code가 idempotency_key_mismatch인 400으로 거부됩니다.
  • 키의 범위는 인증된 호출자로 한정됩니다. 서로 다른 두 API 키나 사용자는 충돌 없이 같은 키 값을 사용할 수 있습니다.
  • 인증되지 않은 요청과 POST가 아닌 메서드에서는 헤더가 무시됩니다. GET, PATCH, DELETE 요청은 안전하게 재시도할 수 있습니다.
  • 키가 포함된 첫 번째 요청이 아직 실행 중일 때 재시도하면 error.code가 idempotency_request_in_progress인 409가 반환됩니다. 첫 번째 요청이 알 수 없는 결과로 실패한 경우(예: 요청 도중 서버 충돌), 키가 만료될 때까지 재시도는 계속 해당 409를 반환합니다. API는 요청을 두 번 실행할 위험을 절대 감수하지 않습니다.