Skip to main content
Idempotency ensures that retrying the same request produces the same result. If a payment request fails due to network issues, you can safely retry it without creating duplicate payments.

​
How it works

Include an Idempotency-Key header when creating payments: 
response = await client.post(
    "https://api.natural.co/payments",
    headers={
        "Authorization": "Bearer sk_ntl_prod_abc123...",
        "Idempotency-Key": str(uuid.uuid4())
    },
    json={...}
)
Natural stores the key and response. On subsequent requests with the same key:
  • Same key + same data → Returns the original response (cached)
  • Same key + different data → Returns 409 Conflict
  • Different key → Creates a new resource
Keys are scoped per user, so different API keys will have independent idempotency namespaces.

​
Best practices

Do:
  • Use UUIDs for random keys (guaranteed unique)
Don’t:
  • Use timestamps (clock skew defeats idempotency)
  • Reuse keys for different logical operations

​
When to retry

ErrorAction
Network/timeoutRetry with same key, exponential backoff
5xx server errorRetry with same key, exponential backoff
409 ConflictCheck original request; use new key if needed
Other 4xxDon’t retry — fix request data first