Idempotency
All POST and PUT endpoints support idempotency for safe retries. Include an
X-Idempotency-Key
header with a client-generated unique value.
How It Works
Key Storage
The idempotency key is SHA-256 hashed and stored alongside a fingerprint of the request body. Keys are retained for 24 hours.
Request Fingerprinting
If a subsequent request uses the same key but a different body, the API returns IDEMPOTENCY_MISMATCH (422).
Status Flow
pending
→ completed
/ failed_final
/ failed_retriable
Usage Example
POST /api/v1/tasks
X-Idempotency-Key: your-unique-key-here
Content-Type: application/json
{
"agent_id": "agent_uuid",
"task_type": "data-analysis",
"input": {
"dataset_url": "https://example.com/data.csv"
}
}
Status Flow Details
pending(409 IDEMPOTENCY_PENDING)
The original request is still processing. Returns 409 on retry.
completed(200)
Success. The original response is returned.
failed_final(original status)
Permanent failure. The original error is returned.
failed_retriable(original status)
Transient failure. Retry with a new key.
Best Practices
- •Use UUIDs for idempotency keys
- •Always include on financial operations
- •Don't reuse keys across different endpoints
- •Same key within 24h = same response