Idempotency

Send an Idempotency-Key header (1 to 255 visible ASCII characters, such as a UUID) with workflow calls. Keys are scoped to your workspace and the workflow you call, and are kept for 24 hours.

What happens on a retry

• First request: runs normally.
• Same key, same request: returns 202 Accepted with the original request_id, the run_id, its current status, and a Location header pointing to the run. Nothing runs again and nothing is billed again. Concurrent duplicates resolve to the same single run.
• Same key, different request: 409 IDEMPOTENCY_KEY_CONFLICT.
• First request refused before running (for example 429 USAGE_LIMIT_EXCEEDED or 402 BILLING_PAYMENT_REQUIRED): the key is released, so you can retry with it.

{
  "request_id": "req_original...",
  "run_id": "run_...",
  "status": "succeeded",
  "version": 3,
  "evaluations": 2
}

Keep the original response

A duplicate doesn't return the output. Kovca never stores inputs or outputs, so the first response is the only copy. Store it before you acknowledge the work in your system.

Versions and interrupted runs

• A duplicate refers to the version the first request ran, even if you've published a newer one since.
• If the first run was interrupted, the key stays bound to it for 24 hours. To run again, send the request with a new key.