DOCS

현황 

Idempotency-key 지원은 현재 부분적으로 제공됩니다. order-billing retry 및 refund-billing retry flow 등 선택된 내부 retry mutation은 이미 idempotency key를 accept하며 downstream payment-processor call 중복을 방지하는 데 사용합니다. Zonos Graph의 모든 customer-facing create mutation에 표준화된 idempotencyKey argument는 아직 없으며, roadmap에 있습니다. 출시 전까지는 아래 패턴을 사용하여 mutation을 안전하게 retry할 수 있도록 하세요.

기본적으로 안전한 mutation 

일부 mutation은 제공하는 stable identifier로 upsert하기 때문에 본질적으로 idempotent합니다. 동일한 input으로 호출하면 결과가 동일하며 duplicate 생성 위험이 없습니다.

  • 고유 merchant-supplied identifier(예: order externalId)를 받는 mutation은 repeat call 시 새 record를 생성하지 않고 기존 record를 반환합니다.
  • Read-only operation(query)은 항상 retry해도 안전합니다.

생성하는 resource에 자체 stable identifier를 attach할 수 있다면 해당 경로를 선호하세요.

본질적으로 idempotent하지 않은 mutation을 위한 패턴 

merchant-supplied key 없이 resource를 생성하는 mutation의 경우, at-most-once로 처리하세요.

  1. 전송 전 request를 persist합니다. network call 전에 자체 database에 row(status pending)를 기록합니다.
  2. mutation을 전송합니다. 성공 시 반환된 resource id를 pending row에 기록합니다(status committed).
  3. network error 발생 시 무분별하게 retry하지 마세요. Zonos Graph를 query하여 resource가 생성되었는지 확인합니다(예: account에서 최근 몇 분 내 생성된 resource를 list하거나 correlate할 수 있는 관련 resource를 query). resource가 없음을 확인한 경우에만 retry합니다.
  4. 자체 database에 unique constraint를 사용하여 request를 나타내는 business key 기준으로 application에서 duplicate retry가 double-submit되지 않도록 합니다.

Webhook delivery는 at-least-once입니다 

Zonos webhook을 consume할 때 handler를 idempotent하게 설계하세요. 동일 event가 두 번 이상 delivery될 수 있습니다. event id로 deduplicate합니다. event id field는 Webhooks를 참조하세요.

플랫폼의 향후 방향 

기본 platform은 billing retry에 대해 production에서 idempotency-key flow를 이미 실행합니다. key는 retry attempt를 scope하고 duplicate payment-processor call을 방지합니다. customer-facing create mutation에 optional idempotencyKey argument로 동일 패턴을 expose하는 작업을 진행 중입니다. 제공 시 Graph는 retention window 내 동일 key로 후속 call에 대해 original response를 반환합니다. surface가 generally available이 되면 이 page를 업데이트합니다.

customer-facing mutation에 표준화된 idempotency key가 integration을 blocking한다면 contact support로 문의하세요.

이 페이지가 도움이 되었나요?