Skip to main content

Idempotency and retry

Reliability uses two different identities:

  • Idempotency-Key identifies one transport submission whose canonical payload must remain identical.
  • external_ref identifies the same business row even when it is submitted under a new transport key.

If the connection is lost after CFO may have accepted a request, reload the canonical payload and original Idempotency-Key from the durable outbox. Retry them exactly. CFO must return the original job without creating another business row. Never create a new key just because no response arrived.

Mandatory cases are: same-key/same-payload returns the same job; same-key/changed-payload fails with IDEMPOTENCY_KEY_REUSED; a new key with the same external_ref becomes skipped_duplicate; a new key with a new external_ref creates exactly one row; and an ERP restart retains all identities and hashes.

Use bounded backoff for 429 and retryable 5xx. Honor Retry-After. Every retry must use the frozen request, not re-read ERP data and silently change the payload mid-flight.