---
title: "Retries and receipts"
description: "Recover uncertain API writes with idempotency keys and operation receipts."
canonical_url: "https://hoplite.sh/docs/factory/retries"
markdown_url: "https://hoplite.sh/docs/factory/retries.md"
---

# Retries and receipts
URL: /docs/factory/retries
LLM index: /llms.txt
Description: Recover uncertain API writes with idempotency keys and operation receipts.
Related: /docs/factory, /docs/api/authentication

# Retries and operation receipts

Keep your workflow recoverable when a request fails or its outcome is unknown. Hoplite's idempotency keys and operation receipts let your backend reconcile a write before deciding what to do next.

Send a stable `Idempotency-Key` on every service-account write. Assign one key to each logical operation in your job, and persist both the key and the request inputs before sending it.

```text title="Keys for one job"
factory-job-001:thread
factory-job-001:pr
factory-job-001:merge
```

## Retry the same operation

Reuse the same key and request after a transport failure or retryable server response. A different payload with the same key returns `409`. Honor `Retry-After` when the server returns `429`.

Settled receipts are retained for at least seven days, and a retry key stays bound to its original operation and payload for that time; use a new key for new work. Keep returned resource IDs in your job record so you can follow execution independently of the receipt.

## Resolve an unknown outcome

Save the response's `x-operation-id` header when available. Read `GET /api/operations/{id}` to inspect the operation receipt and any resource IDs already created.

For example, if thread creation times out, retry the original request with its original key. If the first request created the thread, the retry settles the receipt from it; if Hoplite can prove nothing was created, the retry dispatches again. Generating a new key can create a second thread while the first is still running.

`409 operation_outcome_pending` means the first request may still be running: wait for `Retry-After` and retry the same key. `409 operation_outcome_unknown` means neither outcome could be established. Inspect the receipt and the resource before deciding whether to use a new key; it is not permission to repeat a provider action.

## One-time responses

Replayed receipts omit secrets. Store a new service credential or webhook secret securely when the original response arrives.

If credential rotation succeeds but its response is lost, an owner or admin must issue a replacement. The old credential cannot rotate itself a second time to recover the lost secret.

Preview gateway access is a read, not a receipted write: request fresh access whenever the previous credential expires. See [preview access](/docs/factory#attachments-and-previews).

## Sitemap

See the full [sitemap](/docs/sitemap.md) for all pages.
Well-known sitemap: [/docs/.well-known/sitemap.md](/docs/.well-known/sitemap.md).