Idempotency and safe retries

A network timeout does not tell you whether a mutation failed or completed before the response was lost. For the operations listed below, send an Idempotency-Key so the same logical request can be retried safely.

Request keys and webhook IDs are different

Idempotency-Key protects an outgoing API mutation. A webhook event id protects your receiver from processing the same incoming event more than once.

Send a key

Generate a new UUID for each new logical mutation and pass it in the request header:

curl -X POST "https://api.ltesocks.io/v2/ports/10000/reset" \
  -H "Authorization: Bearer ${LTESOCKS_API_TOKEN}" \
  -H "Idempotency-Key: 7c838e2d-7d52-42e7-aed1-528829cbd514"

Official SDKs create a key automatically for supported mutations. Pass a stored UUID explicitly when continuing the same logical request across application restarts:

JavaScript

const port = await client.ports.reset({
  id: '10000',
  idempotencyKey: '7c838e2d-7d52-42e7-aed1-528829cbd514',
});

Python

from uuid import UUID

port = client.ports.reset(
    "10000",
    idempotency_key=UUID("7c838e2d-7d52-42e7-aed1-528829cbd514"),
)

PHP

<?php

$port = $client->ports()->reset(
    '10000',
    '7c838e2d-7d52-42e7-aed1-528829cbd514',
);

Store the key with the method, path, and body until the result is known. Reuse it only for an exact retry of that request. A new business action, or a request with a changed path or body, needs a new UUID.

When the API returns a previously stored result, the response includes:

Idempotency-Replayed: true

The replay preserves the original response and its response headers, including Retry-At and Retry-After when they were present.

Decide whether to retry

Outcome	Action
Connection closed or timed out before a response	Retry the exact request with the same key
The resource already shows the requested change	Do not send the mutation again
Validation or authentication error	Fix the cause; a changed request uses a new key
Reset cooldown response	Wait for Retry-After or Retry-At, then decide whether the same logical request is still needed
Intentionally starting another mutation	Generate a new key

Use bounded exponential backoff with jitter for transient failures. Idempotency prevents duplicate execution; it does not make unlimited retries or high concurrency safe.

Supported operations

The public contract accepts Idempotency-Key on these mutations:

Area	Operations
Account	POST /user/preferences
Ordering	POST /ports/order
Plan	POST /ports/{id}/extend, POST /ports/{id}/plan
Port settings	POST /ports/{id}/tags, POST /ports/{id}/autorenew, POST /ports/{id}/signature, POST /ports/{id}/credentials, POST /ports/{id}/autoreset
Connection	POST /ports/{id}/reset

Do not attach the header to every POST by default. For example, the port filter operation POST /ports and compatibility delete operations do not document idempotency support. Check the API reference for the header on the specific operation.

For reset-specific cooldown and completion behavior, see Port reset and readiness.