Retries & idempotency
How to replay traffic without duplicating side effects.
Client retry policy
- Retry GET and other safe reads on transient network errors.
- For POST, only retry when you know the operation is idempotent for your use case or you supply an idempotency key where supported.
- Use exponential backoff with jitter and a max attempt count; surface permanent failures to operators.
Idempotency matrix (API)
| Operation | Mechanism | Notes |
|---|---|---|
POST .../agents/:id/execute | JSON idempotency_key | Same agent + key returns stored outcome when previously completed. |
POST .../agents/:id/inference | idempotency_key | Same behavior family as execute for template inference paths. |
POST .../agents/:id/score_lead | idempotency_key in body | Use inbound event id or stable composite key. |
POST /workflows | None (default) | Each call can create a new workflow — dedupe in your orchestrator. |
POST /workflows/:id/test | N/A | Safe to retry for debugging; may create multiple test records depending on version. |
POST /webhooks | N/A | New subscription per request — avoid accidental duplicates. |
Operational notes
Inspect GET /api/v1/agents/:id/executions to confirm whether a retried call attached to an existing execution row. Failed executions may be visible separately from successful deduplicated replays.