멱등 키
System One API 의사결정 요청에 멱등 키를 보내 이중 차감 없이 안전하게 재시도하세요.
새로운 논리 작업 → 새 임의 UUID. 같은 작업의 재시도나 복구 → 저장해 둔 같은 키와 완전한 요청. 같은 입력을 의도적으로 다시 평가하는 것은 재시도가 아니라 새 작업입니다. 작업 키를 쓰면 응답을 잃은 뒤에도 평가나 차금 없이 성공한 결과를 HTTP나 SDK 클라이언트가 복구할 수 있습니다. 이 규칙은 호스팅 API와 세션 Playground에 적용되며, 독립 SDK 어댑터나 직접 제공자에까지 일반적으로 적용되지는 않습니다.
왜 필요한가
타임아웃, 네트워크 오류, 5xx 응답 뒤에 같은 논리 요청을 다시 보내면 두 번 평가되고 두 번 차금될 수 있습니다. Idempotency-Key 헤더는 이 중복을 막습니다. 같은 키와 같은 본문으로 재시도하면 서버는 저장된 결과를 그대로 반환하고 다시 평가하지 않습니다.
키는 작업 하나에 하나씩 사용하세요. 첫 전송 전에 UUID를 한 번 만들고, 완전한 요청과 함께 보관하세요. 전역 환경 변수 키, 여러 작업이 공유하는 상수, 콘텐츠 해시를 쓰지 마세요. 같은 내용이라도 서로 다른 유료 평가일 수 있습니다. 키는 1–128자이며 문자나 숫자로 시작하고 이후에는 문자, 숫자, 점, 밑줄, 콜론, 하이픈을 쓸 수 있습니다.
| 상황 | 작업 키와 요청 |
|---|---|
| 새 의사결정 또는 새 작업 | 새 UUID와 완전한 요청을 만드세요. |
| 같은 입력을 의도적으로 다시 평가 | 요청 본문이 같아도 새 UUID를 만드세요. 새로운 유료 작업입니다. |
타임아웃, 응답 유실, request_in_progress 뒤 재시도 | 기존 작업의 키와 변경되지 않은 완전한 요청을 재사용하고 재시도 지연을 지키세요. |
| 애플리케이션 크래시나 재시작 뒤 복구 | 첫 전송 전에 영구 저장한 작업 전체를 불러오세요. 작업을 새로 만들지 마세요. |
| 같은 계정에서 다른 API 키 사용 | 복구에는 같은 작업 키를 유지하세요. 자격 증명을 바꿔도 별도 네임스페이스는 생기지 않습니다. |
어떻게 보내는가
헤더 이름은 Idempotency-Key이고 선택 사항입니다. 형식은 ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$입니다. 유효하지 않은 값은 HTTP 422 invalid_idempotency_key로 거절됩니다. 키는 계정 범위이며 업스트림으로 전송되지 않습니다.
curl --include 'https://system-one.dev/v1/systemone' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: YOUR_OPERATION_KEY' \
--data-binary @request.json서버는 검증된 정규화 요청을 비교합니다. 공백 서식과 객체 키 순서는 영향을 주지 않습니다. 배열 순서, 점수 루브릭 순서, 필드 값, null과 생략의 차이는 영향을 줍니다. 같은 키에 다른 요청을 보내면 409 idempotency_conflict가 반환됩니다.
모델을 명시적으로 보내고 저장하세요. 생략된 모델은 비교 전에 서비스 기본값으로 해석됩니다. 명시적 별칭과 버전 이름도 요청 동일성의 일부이며, 같은 모델로 해석되더라도 마찬가지입니다. 복구할 때 요청 ID를 응답의 해석된 모델로 바꾸지 마세요.
이미지는 요청 동일성의 일부입니다. 모든 base64 문자열, 미디어 타입, 표현 방식, 배열 순서가 포함됩니다. 같은 키에서 이미지 순서를 바꾸거나 교체하면 충돌합니다. images: []는 텍스트 전용 모델에서 유효하지만 필드를 생략하는 것과 같지는 않습니다. 복구에는 원본 본문을 보관하세요.
SDK 헬퍼
SDK는 자동으로 멱등 키를 만들지 않습니다. 같은 키와 요청을 함께 보관하고 재사용하는 것은 애플리케이션의 책임입니다.
const result = await client.evaluate(operation.request, {
maxRetries: 0,
timeoutMs: 30_000,
headers: { 'Idempotency-Key': operation.idempotencyKey },
});SDK 예제나 Fetch 전송 계층은 maxRetries: 0으로 자동 재시도를 끕니다. 재시도 정책은 네트워크 오류와 일부 HTTP 실패를 재시도할 수 있지만 서로 다른 409 상태를 자동으로 해결하지는 않습니다. 재시도를 켜더라도 같은 키와 본문이 필요합니다.
실제 애플리케이션에서는 작업 전체(키, 선택한 모델, 완전한 요청)를 첫 전송 전에 애플리케이션의 작업 레코드에 영구 저장하세요. 크래시 후에는 새 UUID를 만들거나 새 프롬프트나 현재 모델 선택으로 요청을 다시 만들지 말고 그 레코드를 불러옵니다. 프로세스 내 재시도는 같은 operation 객체를 유지하고 호출만 다시 실행합니다. 재시도 코드 안에서 새 키를 만들면 다시 차금될 수 있습니다.
재플레이와 재계산의 차이
| 기존 작업 상태 | 같은 키와 본문에 대한 응답 | 처리 |
|---|---|---|
| 보관된 작업 없음 | 새 평가가 시작되고 크레딧이 차감됩니다. | 결과가 확정될 때까지 키를 보관하세요. |
| 아직 처리 중 | 409 request_in_progress와 Retry-After. | 기다린 뒤 같은 키와 본문으로 재시도하세요. |
| 성공함 | 저장된 상태, 본문, 허용된 헤더를 다시 평가나 차금 없이 반환합니다. | 복구된 결과를 사용하세요. |
| 실패하고 크레딧이 반환됨 | 409 idempotency_failed. | 의도적인 새 시도일 때만 새 키를 쓰세요. |
| 본문이 다름 | 409 idempotency_conflict. | 원본 본문을 복원하거나, 진짜 다른 작업이면 새 키를 쓰세요. |
| 답을 더 이상 사용할 수 없음 | 410 idempotency_expired. | 새 작업을 시작하기 전에 원래 작업을 확인하세요. |
성공한 재플레이는 X-Idempotency-Replayed: true, X-System-One-Credits: 0, 원래의 X-Request-Id를 포함합니다. 모델을 다시 평가하지 않고 저장된 응답을 재사용하며 값을 다시 반올림하지 않습니다. 재플레이 시도도 계정 할당량을 소비하지만 새로운 차금은 발생하지 않습니다. 응답은 Cache-Control: no-store를 사용하며 브라우저나 프록시 캐싱이 멱등성 메커니즘이 아닙니다.
24시간 창
완료된 작업은 요청 생성 시점부터 24시간 동안 키로 복구할 수 있습니다. 그 시간이 지나면 같은 키가 새 유료 작업을 시작할 수 있습니다. 만료 오류를 반환하지 않을 수도 있습니다. 이것은 영구적인 중복 방지가 아닙니다.
작업 키 없이 같은 요청을 반복하면 별개의 평가입니다. 중요한 답은 재플레이에 기대지 말고 애플리케이션에 저장하세요.
일반적인 실패 평가에서는 예약된 크레딧이 오류 응답 전에 반환됩니다. 중단은 작업을 대기 상태로 남길 수 있으며 15분 넘게 대기 중인 요청은 정산 대상이 될 수 있지만, 이는 즉시 완료나 환불 기한이 아닙니다. 결과가 확정될 때까지 원래 키와 요청 ID를 보관하세요. 503 request_reconciliation_pending를 받은 요청은 아직 과금이 확정되지 않은 상태이며 X-System-One-Credits가 생략됩니다. 누락은 0을 의미하지 않습니다. 원래 키와 X-Request-Id를 유지하고 콘솔 사용량을 확인하세요. 오류를 피하려고 새 키로 바꾸지 마세요.
흔한 실수
- 재시도마다 새 키 만들기. 같은 작업의 재시도에는 같은 키를 쓰세요. 새 키는 새 과금 작업을 만듭니다.
- 서로 다른 본문에 키 재사용하기. 본문이 바뀌면
409 idempotency_conflict가 납니다. 본문을 복원하거나 새 작업을 새 키로 시작하세요. - 공유 환경 변수로 키 고정하기. 작업마다 키를 새로 만들고 작업 레코드에 보관하세요.
- 키만 저장하고 요청을 버리기. 복구에는 키와 완전한 요청이 모두 필요합니다.
- 24시간을 영구 보존으로 보기. 창이 지나면 같은 키가 새 유료 작업을 시작할 수 있습니다.
자주 묻는 질문
Q: System One API의 멱등 키란? A: 클라이언트가 만든 토큰으로, 재시도 시 같은 의사결정 결과를 반환하고 크레딧 이중 차감을 막습니다.
Q: 언제 보내나요? A: 타임아웃·네트워크 오류·5xx 이후 같은 논리 의사결정을 재시도할 수 있을 때.