Idempotency
Safely retry public API write requests.
Use idempotency keys when retrying write requests. This prevents duplicate records when a network timeout happens after Agiled already processed the request.
Use them for every integration write where a retry might happen automatically.
Idempotency is most important for imports, queues, webhooks, and scheduled jobs because those systems often retry without a person watching.
Header
Send a unique key in the Idempotency-Key header:
curl "$AGILED_API_BASE_URL/public/v1/contacts" \
-X POST \
-H "Authorization: Bearer $AGILED_API_TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: contact-import-0001" \
-d '{"first_name":"Avery","last_name":"Stone","email":"avery@example.com"}'How It Works
For matching organization, method, path, and idempotency key:
- The first successful operation stores the response.
- A retry with the same request body returns the stored response.
- A retry with a different request body returns an idempotency conflict.
Stored idempotency keys expire after 30 days.
Store the key with your source job or external record ID so later retries use the same key.
Store the response too when possible. If the source job resumes later, it can reuse the Agiled record ID instead of searching by name or guessing whether the write succeeded.
When to Use It
Use idempotency keys for create, update, and delete requests from integrations, imports, queues, and scheduled jobs.
Key Design
Use stable keys such as source-system-record-id-action-version. Do not use a
new random key for every retry, or Agiled will treat each retry as a new write.
If the request body changes, use a new key and treat it as a new operation.
Troubleshooting
If you receive an idempotency conflict, compare the current request body with the body sent with the original key. Either retry the original body or create a new key for a genuinely new operation.
If duplicates still appear, confirm the retry path is reusing the same key and not generating a fresh random value on every attempt.
Good Key Examples
Good keys are stable and meaningful to your integration:
hubspot-contact-123-create-v1stripe-payment-pi_123-record-v1migration-row-00429-create-contact-v1order-1001-create-invoice-v1
Avoid timestamps or random UUIDs for automatic retries. They are useful for unique operations, but they defeat duplicate prevention when the same job runs again after a timeout.