Idempotency
Retries improve reliability, but they introduce a new challenge - what happens if the original request actually succeeded, but the response was never received?
Without idempotency, retrying a request could accidentally execute the same operation multiple times.
For example:
- Charging a customer twice
- Creating duplicate invoices
- Sending the same email multiple times
- Creating multiple GitHub issues
- Provisioning duplicate cloud resources
To prevent this, Swytchcode supports automatic idempotency-key injection for supported integrations. It’s opt-in per integration - see Configuring Idempotency below - but once enabled, key generation and reuse across retries is handled for you.
Why Idempotency Matters
Imagine an AI agent creating a payment.
Create Payment │ ▼ Provider receives request │ ▼Network connection lost │ ▼Client never receives responseAt this point, your application doesn’t know whether:
- the provider never received the request, or
- the provider successfully completed the request but the response was lost.
If the client retries blindly, the payment could be processed twice.
The Problem Without Idempotency
Attempt 1
↓
Payment Created
↓
Network Failure
↓
Retry
↓
Second Payment Created ❌Even though the retry was caused by a network failure, the provider receives two independent requests.
How Swytchcode Solves This
For supported providers with idempotency enabled (execution_policy.idempotency.mode: "dynamic" in manifest.json), Swytchcode automatically attaches an idempotency key to mutating API requests.
Create Payment │ ▼Idempotency-Key:b7fd8a91... │ ▼Provider APIIf the request is retried, the same idempotency key is sent again.
The provider recognizes that it has already processed a request with that key and returns the original result instead of executing the operation again.
Retry Flow with Idempotency
Request
↓
Attach Idempotency Key
↓
Provider
↓
Network Failure
↓
Retry
↓
Same Idempotency Key
↓
Provider Returns Previous Result
↓
No Duplicate OperationThis makes retries safe even when the client cannot determine whether the previous request succeeded.
When Is Idempotency Used?
Idempotency is most valuable for mutating operations.
Examples include:
- Creating payments
- Charging cards
- Creating invoices
- Creating subscriptions
- Sending emails
- Creating repositories
- Creating cloud infrastructure
Read-only operations such as GET requests generally do not require idempotency.
How Keys Are Generated
Idempotency is off by default (mode: "none") - Swytchcode does not attach an idempotency key to any request unless you turn it on for that integration’s execution_policy. Once enabled (mode: "dynamic"), a unique key is generated for every API call:
Call
↓
Generate Unique Key
↓
Execute OnceEach individual exec call gets its own key, so a retry of that same call reuses it, but a second, unrelated call gets a new one.
Configuring Idempotency
Idempotency is configured in the execution_policy section of manifest.json.
{ "execution_policy": { "idempotency": { "mode": "dynamic", "header_name": "Idempotency-Key" } }}Every field is optional.
If omitted, Swytchcode uses the default configuration.
Default Configuration
| Field | Default |
|---|---|
mode | "none" |
header_name | "Idempotency-Key" |
How It Works with Retries
Retries and idempotency work together.
Execute Request │ ▼Attach Idempotency Key │ ▼Send Request │ ▼Temporary Failure │ ▼Retry │ ▼Reuse Same Idempotency Key │ ▼Provider Returns Original ResultRetries improve reliability.
Idempotency guarantees that those retries remain safe.
Best Practices
- Enable idempotency for mutating APIs.
- Never generate a new idempotency key during a retry.
- Combine idempotency with retries for production workloads.
- Test retry scenarios in sandbox environments before deploying to production.