요약

  • Stripe API v1의 POST는 엔드포인트 실행이 시작된 뒤 첫 상태 코드와 본문을 저장하며, 500도 포함한다. 같은 멱등 키로 재시도하면 저장 기간 동안 그 응답이 돌아온다.
  • Stripe는 500 뒤의 실제 결과를 미확정으로 본다. 복구 과정에서 객체가 생성돼 웹훅이 올 수 있지만 캐시된 응답은 바뀌지 않는다. API v2는 다른 재시도 방식을 쓴다.

빨간 영수증은 장부가 아니다

애플리케이션이 요청을 보내고 500을 받는다. 같은 키로 다시 보내자 또 500이다. 두 번 실패했다고 기록하기 쉽지만 API v1에서는 두 번째 응답이 첫 응답의 재생일 수 있다. Stripe는 엔드포인트가 실행을 시작한 뒤 결과를 보관한다. Idempotent-Replayed: true가 재생 여부를 알린다. 오류 횟수만 세는 대시보드는 실제 업무 결과 대신 영수증 수를 센다.

Stripe는 500에도 부수 효과가 있었을 수 있다고 밝힌다. 사고 복구 과정에서 실패한 작업을 조정하고 생성된 객체에 대한 웹훅을 보낼 수 있다. 그래도 예전 500은 고쳐지지 않는다. 조정이 매번 성공하는 것도 아니다. 따라서 응답 기록과 객체 상태를 분리해 확인해야 한다.

첫 호출 전에 로컬 업무 ID를 만들고 리소스 메타데이터에 담아야 한다. 500을 받은 팀은 해당 객체를 조회하고 Dashboard의 요청 기록과 서명 확인된 웹훅을 대조한다. 첫 결과가 불명확한 채 새 멱등 키를 발급하면 다른 작업이 시작될 수 있다. 고객 지원팀이 본 빨간 화면과 재무팀이 찾은 객체를 같은 ID로 묶는 이유다.

API v2는 재시도 계약이 달라진다. Stripe 설명에 따르면 이미 성공한 작업은 반복하지 않고, 실패하거나 일부만 끝난 작업은 가능한 경우 완료해 갱신된 응답을 준다. v1에서 v2로 옮길 때 재시도 버튼의 뜻까지 함께 바뀐다. 호출 버전과 실제 객체 상태를 먼저 확인해야 다음 결정을 내릴 수 있다.

출처