Guides / reliability

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.

terminal

1idempotency_key="$(openssl rand -hex 24)"23curl --fail-with-body --request POST \4  "$WILDFLOWER_URL/v1/sandboxes" \5  -H "Authorization: Bearer $WILDFLOWER_API_KEY" \6  -H "Idempotency-Key: $idempotency_key" \7  -H "Content-Type: application/json" \8  --data '{"provider":"e2b","image":"base","timeout":300}'

Never mutate a request behind the same key

Reusing a key with different input returnsidempotency_conflict. Concurrent attempts can returnidempotency_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 reads Wildflower's project registry without contacting a provider. Results are newest first and include deleted tombstones. Treat each status as cached atstatusObservedAt; pass an opaque nextCursor back ascursor 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 referencefor the exact request and header types.