Use one Idempotency-Key for one mutation intent. If a response is lost, retry that intent with the same key and request inputs. A completed intent can return its saved response without repeating the HTTP operation's effect.
The operation reference declares whether the header is required. HTTP POST alone does not determine the policy.
| API | Required operations | Exceptions |
|---|---|---|
| Platform v2 | Declared state changes and external actions, including balance refresh, channel tests and notification resends | GET, balance search and EVM simulation |
| Management | Every POST, PATCH and DELETE on this surface | GET; dashboard-session operations are outside this API-key surface |
| VKS | Every POST and DELETE, including signer invitations, abort actions and transaction send requests | GET |
These rules do not extend to blockchain JSON-RPC or gRPC calls. HTTP effect deduplication does not guarantee exactly-once webhook delivery, signing or blockchain execution. A VKS send 202 records the request; follow transaction logs for its outcome, and check chain confirmation separately.
Send exactly one Idempotency-Key header occurrence with 1 to 128 visible ASCII bytes (0x21 through 0x7e, pattern ^[!-~]+$). Values are opaque and case-sensitive. A UUID is allowed but not required. Do not trim, lowercase or split the value: a comma is literal data. Repeated headers are invalid even if their values match; whitespace and non-ASCII characters are invalid.
A binding identifies the caller, operation and target. Platform also scopes it to the project; VKS scopes it to the workspace. Management targets identify the relevant workspace or resource. The same text used by another caller or against another target is not a recovery mechanism. Keep the original caller and scope when retrying.
Before the first attempt, save the key, method, target, request parameters and complete body with your business intent. Preserve them across process restarts. Generate timestamps, expiry values and random body fields once; a retry must not refresh an invoice's expires_at. Each distinct intent gets a different key. Do not reuse a completed key for a later action, even after its response expires.
Every attempt checks current authentication and permissions, including replay. The key grants no access. Revoked credentials or removed permissions can prevent replay; switching to another caller can produce a separate effect.
- Open Register an external address. Use a project key with
api:address:write. - Choose your address, chain family and label. Generate one
Idempotency-Keyand save it with the complete request body in your durable intent record. - Send the request using the operation page's request builder or one of its client examples.
- If the response is lost, retry with the same key, body, parameters and credentials. Do not generate a new key while the outcome is unknown.
- Save the returned resource identity. For another address or label, resolve the original intent before starting a new one.
| Result | Replay window and conditions |
|---|---|
| Ordinary successful response | 24 hours from original successful completion |
| Platform response containing a webhook signing secret | 60 seconds from completion, only while that secret is current; replacement, deletion or revocation can make replay unavailable |
| API/RPC key secret created through the Management API | 60 seconds from successful creation, with current access and permitted key state; revoked or deleted keys are not restored |
VKS POST /signers invitation secret | 60 seconds from successful creation, only while the invitation is unused, unexpired and not deleted |
Retries never extend these windows. Save secrets immediately in a secrets manager; later GET requests do not recover their plaintext.
The VKS invitation's replay window is distinct from its first-use deadline and from registration retry by the same signer using its previously received token. An invitation can remain usable after its HTTP response can no longer be replayed. After successful registration, the same signer can retry setup with its original token even after the first-use deadline, until the signer is deleted.
A replay returns the original response snapshot, including its original resource state. Use the resource's GET operation for current state when you know its ID. VKS abort/deletion and Management project-deletion replays can return their original success after changing or removing the target, while current workspace access still permits replay. A removed workspace does not remain accessible through its old key.
A durably bound key stays bound permanently after response expiry. Expiry does not run the operation again or permit another effect with that binding. Header rejection or validation before an effect does not by itself establish a durable binding; not every attempted key is reserved, and not every error response is cached.
Read the problem code as well as the HTTP status. Other business conflicts can also return 409; see Errors.
| Response | What to do |
|---|---|
Missing, malformed or repeated header: 400 | Fix the header. Platform and VKS use idempotency_key_invalid; Management documents the InvalidRequestProblem response schema. A rejected header does not establish a saved effect. |
409 idempotency_in_progress | Another attempt with this binding is running. Back off and retry the same key and inputs; do not launch parallel replacements. |
409 idempotency_request_mismatch | Compare against the saved original method, target, parameters and body. Restore the original inputs for a retry; changed inputs must not overwrite this intent. |
409 idempotency_result_expired | The saved response is no longer available. Reconcile the old outcome; the operation is not repeated. VKS also uses this code when a signer invitation is no longer eligible for secret replay. |
409 idempotency_result_unavailable (Platform) | Check current resource/secret state. Replay cannot restore a replaced or removed secret. |
Current 401, 403 or scope/resource 404 | Restore legitimate access where possible. The intent key bypasses no access check. |
Timeout, connection loss or 5xx | The effect may already have occurred. Use backoff with the same key and unchanged inputs while replay is available. |
| Explicit validation failure before any effect | Correct the invalid input according to the operation. This differs from a lost response with an unknown outcome; do not assume all failures have a replayable result. |
Never automatically generate a fresh key after an expired, unavailable or uncertain response. A new key can create a second effect. A deliberate replacement is a new business action after reconciling the original outcome.
If you know the resource ID, read it and its relevant logs. If a creation response was lost and you do not know the ID, use only list/filter operations actually provided by that API and your saved business correlation data to identify the result. There is no public idempotency-status or lookup-by-key endpoint. Listing may not identify the resource uniquely, and metadata is not a universal lookup filter. If the outcome remains unresolved, retain the original intent and request evidence for support; do not assume that a lost resource ID can always be recovered.