---
title: "Retry what you can prove."
description: "Retry Wildflower Computer requests safely using create idempotency keys, explicit reconciliation, rate-limit headers, and request correlation."
canonical: "https://wildflower.computer/docs/reliability/"
openapi_version: "0.8.0"
source_revision: "788b7325a454b8b753a7d614247d5694bad5c967"
---

# Retry what you can prove.

Network failures do not always reveal whether a provider created a resource. Wildflower fails closed around uncertain outcomes and gives callers explicit tools for replay, reconciliation, and support.

## Give every logical create one key

Generate an idempotency key before the first create attempt and persist it with your job. A completed request replayed with the same key, body, and non-secret provider connection context returns the original sandbox.

```bash
idempotency_key="$(openssl rand -hex 24)"

curl --fail-with-body --request POST \
  "$WILDFLOWER_URL/v1/sandboxes" \
  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \
  -H "Idempotency-Key: $idempotency_key" \
  -H "Content-Type: application/json" \
  --data '{"provider":"e2b","image":"base","timeout":300}'
```

> **Never mutate a request behind the same key**
>
> Reusing a key with different input returns`idempotency_conflict`. Concurrent attempts can return`idempotency_in_progress`. Keep one key attached to one immutable logical create.

## Use a small retry policy

| Outcome | Next action |
| --- | --- |
| `429 rate_limited` | Wait for `Retry-After`, then retry with jitter. |
| `provider_unavailable` | Back off. For create, retain the original idempotency key and body. |
| `idempotency_in_progress` | Wait, then replay the same create rather than issuing a new one. |
| `idempotency_outcome_unknown` or`sandbox_create_outcome_unknown` | Do not blind-retry. Retain the returned operation ID and reconcile. |
| Validation or authentication error | Fix the request or credentials; retries cannot change the result. |

## Reconcile from project state

[List sandboxes](https://wildflower.computer/docs/reference/list-sandboxes/) reads Wildflower's project registry without contacting a provider. Results are newest first and include deleted tombstones. Treat each status as cached at`statusObservedAt`; pass an opaque `nextCursor` back as`cursor` to continue.

## Retain response metadata

### X-Request-Id

Keep this server-generated correlation ID with errors and support reports.

### Server-Timing

Separates total API time, application time, and provider-adapter time when a provider call occurred.

### Idempotency-Replayed

Identifies a successful response recovered from a prior create.

### SDK observers

Generated clients expose response metadata without replacing their normal return values.

> **Provider choice remains explicit**
>
> Wildflower does not fail over to another provider. A retry addresses the same adapter and logical operation; it never migrates sandbox state.

See the [generated create reference](https://wildflower.computer/docs/reference/create-sandbox/)for the exact request and header types.