Idempotency

Networks fail. When a POST times out you cannot know whether the server processed it. Send an Idempotency-Key header so that retrying is safe: the request runs once and every retry gets the same answer.

curl -X POST "https://sdk.tilt-pay.com/v1/users" \
  -H "Authorization: Bearer $TILT_PAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7b1c0d36-5f0e-4d2a-9a43-0b8c6e2f1a90" \
  -d '{"phone": "+33612345678"}'

Rules#

• The header is accepted on every POST. It is optional but recommended. Without it there is no guarantee: the request is not replayed.
• The key is 1 to 255 printable characters. A UUID v4 is recommended. An invalid key returns 400 idempotency_key_invalid.
• The scope is (project, environment, key): the same key can be used in sandbox and live without clashing.
• The first request runs and its response is remembered for 24 hours. Server errors (5xx) are not remembered, so a retry runs again.
• Replaying the same method, route and body with the same key returns the same status and body, with the header Idempotent-Replayed: true.
• The same key with a different body or route returns 422 idempotency_key_reuse.
• If the original request is still running, the retry returns 409 idempotency_in_progress: wait a moment and try again.

Which operations need it#

GET requests are naturally safe to retry. The suspend and unsuspend operations are idempotent by nature. Use the header for operations that create something: Create a user, Simulate a scenario and Evaluate Automation Policies.