Skip to main content
Use this recipe when an agent may retry a write because of a timeout, network drop, or interrupted session.

​
Steps

  1. Generate one unique Idempotency-Key for the intended write.
  2. Send the write request with that key.
  3. If the request times out, retry the same method, path, query, and body with the same key.
  4. If the API returns idempotency_conflict, keep the original payload or generate a new key for a new operation.

​
Generate a key

Use a random UUID with a short operation prefix: 
const idempotencyKey = `timer-create-${crypto.randomUUID()}`
Other runtimes can use the same pattern: 
uuidgen

import uuid

idempotency_key = f"timer-create-{uuid.uuid4()}"
Do not use only a date, timestamp, or counter. The key should be stable for one logical write and unique across different writes.

​
Example

curl "https://tickward.com/api/v1/projects/project_123/timers" \
  -X POST \
  -H "Authorization: Bearer tw_your_api_key" \
  -H "Idempotency-Key: timer-create-2f5d5dd1-7a3d-47bb-b31f-5e55fd4d9c9b" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Contract renewal",
    "target_date": "2026-09-01T09:00:00.000Z",
    "timezone": "Europe/Warsaw",
    "notify": true
  }'

​
Recovery

  • rate_limited: retry after the retry-after header.
  • idempotency_key_in_progress: retry the same request after a short delay.
  • idempotency_conflict: do not retry with changed payload under the same key.