Idempotency

Networks drop responses. When a POST times out, you can't tell whether the server did the work or not. An idempotency key removes the guesswork: retry the same request with the same key and you get the same result exactly once, no double charge, no duplicate resource.

The header

Idempotency-Key: <your-unique-string, up to 255 chars>

Choose a value that is unique per logical operation, a UUID (v4) per checkout is ideal. Reuse the same key when (and only when) you're retrying that same operation.

Where it applies

Idempotency is opt-in per endpoint, not blanket coverage. This table is the complete list:

Three endpoints require the header: two charge your wallet directly, placing an order and renewing a service; the third, opening a wallet top-up, doesn't move money itself but opens a payment checkout, and the same guarantee applies: retry with the same key and you get back the same checkout rather than a second one for the same intent. Calling any of the three without the header fails with MISSING_PARAMETER (400) and details: [{ "header": "Idempotency-Key" }].

Semantics

The key is scoped to your account and bound to the exact request (method, path, and body) it first accompanied. Here's how each case resolves:

A request rejected before it could do anything, a validation failure or INSUFFICIENT_BALANCE for example, releases its key. Fix the cause and retry with the same key.

A replayed response carries the marker header so you can tell a fresh success from a replayed one:

HTTP/1.1 201 Created
Idempotent-Replay: true
X-Request-Id: req_8Ke2jP4mQ

Retention

Idempotency records live for 24 hours from creation, then expire. Within that window a retry replays the stored response; after it, the same key is free to be used for a new request. Keep your retry loops well inside 24 hours, and don't recycle a key across unrelated operations.

A safe retry

Generate one key per operation, then reuse it across every retry attempt:

import uuid
import requests

BASE = "https://dashboard.proxio.net/api/v1"
API_KEY = "pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

# One key for this logical purchase, reused on every retry.
idem_key = str(uuid.uuid4())
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Idempotency-Key": idem_key,
}
body = {"category": "RESIDENTIAL", "quantity_gb": 50}

resp = requests.post(f"{BASE}/orders", headers=headers, json=body, timeout=30)
resp.raise_for_status()
# On a timeout or 5xx, retrying with the SAME idem_key is safe: it never
# double-charges. A completed request replays with Idempotent-Replay: true.
print(resp.headers.get("Idempotent-Replay"), resp.json()["data"])

import { randomUUID } from "node:crypto"

const BASE = "https://dashboard.proxio.net/api/v1"
const API_KEY = "pxo_9fJ2kQ7xR4mN8pL1dW6vB3cH5tZ0aYqS7dK2mN9x"

// One key for this logical purchase, reused on every retry.
const idemKey = randomUUID()
const headers = {
  Authorization: `Bearer ${API_KEY}`,
  "Idempotency-Key": idemKey,
  "Content-Type": "application/json",
}
const body = JSON.stringify({ category: "RESIDENTIAL", quantity_gb: 50 })

const res = await fetch(`${BASE}/orders`, { method: "POST", headers, body })
// Retrying with the SAME idemKey after a timeout or 5xx never double-charges.
console.log(res.headers.get("Idempotent-Replay"), (await res.json()).data)

Related pages