본문으로 건너뛰기
Sursa Developers

멱등 요청

Sursa가 이미 처리를 마친 뒤에 요청이 실패할 수 있어요. 연결이 끊기거나, 응답이 도착하기 전에 프로세스가 재시작되는 경우예요. 같은 POST를 다시 보내면 카드나 웹훅이 하나 더 생길 수 있어요. 멱등성 키가 이를 막아 줘요.

모든 POST와 PATCH 요청에 Idempotency-Key 헤더를 보내세요. 이 키로 보낸 요청을 Sursa가 이미 받은 적이 있으면 처리를 다시 실행하지 않고 처음에 저장한 응답을 반환해요.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

반복된 요청은 첫 요청과 같은 상태와 본문을 받고, 헤더가 하나 더 붙어요.

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

반복된 요청에는 별도의 X-Request-Id가 붙어요.

키 고르기

  • 논리적 처리 단위마다 UUID v4 같은 새 무작위 값을 쓰세요. 예: “이 카드 만들기”, “이 웹훅 등록하기”. 그 처리를 재시도할 때마다 같은 값을 쓰고, 다른 처리에는 절대 쓰지 마세요.
  • 직접 가진 데이터가 있다면 거기서 키를 만드는 것이 좋아요. 예: sync-2026-10-24-record-1042. 그러면 메모리를 잃고 재시작된 작업도 같은 키를 다시 보내요.
  • 키는 출력 가능한 ASCII 문자 1~255자예요. 그 밖의 값은 400 상태와 api.idempotency_key_invalid 코드를 반환해요.

Sursa가 키를 처리하는 방식

상황응답
이 키로 보낸 첫 요청평소처럼 처리가 실행돼요.
같은 키, 같은 요청이며 첫 요청이 2xx나 4xx로 끝남저장된 응답이 Idempotency-Replayed: true와 함께 반환돼요. 처리는 다시 실행되지 않아요.
같은 키이며 첫 요청이 아직 실행 중Retry-After: 1과 함께 409 api.idempotency_in_progress. 기다린 뒤 재시도하세요.
같은 키이지만 메서드, 경로, Content-Type, 본문 중 하나가 다름409 api.idempotency_mismatch. 키가 이미 다른 요청에 쓰였어요.
첫 요청이 5xx나 429로 끝남키가 해제돼요. 그 키로 보낸 다음 요청은 처리를 다시 실행해요.
  • 키는 24시간 동안 유효해요. 그 뒤에는 같은 키로 새 처리가 시작돼요.
  • 키는 조직과 호출자별로 구분돼요. 서로 다른 두 API 키는 같은 값을 써도 서로 영향을 주지 않아요.
  • 4xx 오류 응답도 저장돼요. 유효성 검사에 실패한 요청은 같은 키로 반복하면 똑같이 실패해요. 요청을 고친 다음 새 키로 보내세요.

키가 필요한 요청

메서드Idempotency-Key
POST, PATCH보내세요. 반복 요청에 대비해 응답을 저장하는 엔드포인트에는 모두 API 레퍼런스에 이 헤더가 나와 있어요.
GET, PUT, DELETE필요 없어요. 이 메서드는 의미상 반복해도 안전해요. 헤더를 받기는 하지만 아무 효과가 없어요.
검색, 재무 보고서, POST /v1/catalog/resolve처럼 읽기만 하는 POST받기는 하지만 아무것도 저장하지 않아요. 요청이 그냥 다시 실행돼요.

일부 처리는 헤더 없이도 반복해도 안전해요.

  • PUT /v1/cards-by-external-id/{external_id}는 직접 정한 ID로 카드를 생성하거나 교체해요. 같은 내용으로 반복하면 아무것도 바뀌지 않아요.
  • 사용자 지정 소스의 문서는 직접 정한 external_id 값으로 구분돼요. 같은 문서를 다시 보내면 unchanged를 반환해요.
  • POST /v1/chat의 스트리밍 답변은 헤더 대신 본문의 request_id 필드를 써요. Q&A 봇 만들기를 참고하세요.

안전하게 재시도하기

키를 오류의 재시도 규칙과 함께 쓰세요. 첫 시도 전에 키를 한 번 만들고, 같은 처리의 모든 시도에 그 키를 보내세요.