Idempotency

Усі ендпоінти AstroWay API 본질적으로 멱등: 동일한 input은 항상 동일한 output을 반환하며, 크레딧 차감 및 usage 로깅을 제외하고 부수 효과가 없습니다.

이는 네트워크 오류 시 재시도가 안전함을 의미합니다. 하지만 재요청이 크레딧을 두 번 차감하지 않도록 하려면 Idempotency-Key 헤더를 전달해야 합니다.

사용 방법

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - 최대 64자 길이의 임의 문자열이며, 각 논리적 작업마다 고유합니다. 권장 형식은 ULID 또는 UUID v4입니다.

보장 사항

이 키로 첫 요청을 보낸 후 24시간 동안 동일한 키를 사용한 재요청은 동일한 response를 반환하며, 재계산 없이 크레딧을 차감하지 않습니다.
요청 body가 원본과 다르면 409 Conflict와 idempotency_key_reuse 코드를 반환합니다.
24시간이 지나면 키가 사라지고, 같은 키를 사용한 새로운 요청은 일반 요청으로 처리됩니다.

언제 필요할까

외부 시스템(예: 결제 제공자 또는 CRM)으로부터 재시도가 오는 webhook 핸들러에서 (이벤트를 파싱하고 계산을 수행하는 경우)
장애 시 재시도가 표준 동작인 백그라운드 잡에서
테스트가 재실행될 수 있는 CI/CD 파이프라인에서

일반적인 상호작용인 “사용자가 버튼을 눌러 → 지도를 표시”에서는 멱등성이 필요하지 않습니다 - 사용자는 이미 결과를 보게 되며, 보통 재클릭이 없습니다.

언제 사용하면 안 되는지

동일한 요청에 대한 크레딧을 절약하려고 키를 사용하지 마세요: 이를 위해 X-Cache가 있습니다 (무료, 5분)
hash(body)로 키를 생성하지 마세요: 그러면 Idempotency-Key의 기본 동작(본문이 다를 때 재시도 시 409 반환)을 잃게 됩니다.

도움이 되었나요?

수정 제안하기

마지막 업데이트: 2026. 9. 25.