Idempotency and retries
Retry supported writes safely after timeouts or connection failures.
An idempotency key identifies one logical write. If a response is lost, an identical retry with the same key can return the original result without performing the operation again.
Send a stable key
curl --fail-with-body \
--request POST \
--header "Authorization: Bearer $OPENSTEAD_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: create-example-project-001" \
--data '{"name":"example-project"}' \
"https://api.openstead.tech/api/v1/workspaces/$OPENSTEAD_WORKSPACE_ID/projects"Use 1–160 visible ASCII characters without spaces. Persist the key alongside your operation data before sending a request when the workflow can restart.
The legacy JSON-body requestId field is also accepted. If both forms are supplied, they must match. Prefer the header for new REST integrations.
Supported public writes
- Project create, update, and delete.
- Service create, update, delete, archive, restore, and actions.
- Service-variable create, update, and delete.
- Deployment create, cancel, and rollback.
Secret reveal is excluded. Do not attach a key to reveal or assume another dashboard endpoint supports replay. Unsupported operations reject the header with idempotency_not_supported.
The 24-hour window
Successful keyed responses are retained for 24 hours. The key is scoped to the actor, credential, method, and request path within the workspace. Retries must use the same request values, query parameters, and key.
| Response | Meaning |
|---|---|
Idempotency-Replayed: false | This keyed operation was committed now. |
Idempotency-Replayed: true | This is the retained successful response. |
409 idempotency_conflict | The key was already used with different request values. |
A replay returns the original response, including its original queued state. Follow it with a GET when you need current progress. Authorization is checked again, so a stored receipt does not bypass revoked membership or protected-environment rules.
After 24 hours, a key may be processed as a new operation. Reconcile existing state before resubmitting old work.
Retry policy
Retry reads and supported keyed writes after transport failures, 429, or transient 5xx responses. Use exponential backoff with jitter, a finite attempt limit, and a deadline. Honor Retry-After; do not retry earlier because the delay exceeds your own preferred backoff.
Resolve validation, authentication, permission, and conflict errors before retrying. Keep the original key and payload after an uncertain write response.
The Python and TypeScript SDKs generate a key for each supported write invocation and preserve it across automatic retries. A separate method invocation generates a new key unless you supply your own. Use a durable caller-supplied key for retries across process restarts.
Reconciliation cases
idempotency_legacy_conflict identifies a deployment key without a retained response receipt. Read that deployment before starting another one.
idempotency_authorization_changed means your workspace role changed after the original request. Reconcile the operation under your current authority before deciding to submit new work.
Neither conflict is a reason to generate a fresh key automatically.