An idempotency key makes a retry safe: the same request returns the original result and is not charged twice.
Using one#
curl -s https://api.nexus402.dev/v1/mcp \
-H "X-Nexus-Api-Key: nx_dev_..." \
-H "Idempotency-Key: 7f3a9c12-4e5b-4d8a-9f01-2b3c4d5e6f70" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call",...}'Generate a fresh key per logical operation — a UUID is ideal. Reuse it only when retrying that same operation.
A duplicate of the same request#
Returns the original result. It is free: the second call never reaches the tool and never touches your balance. This is what makes a network timeout safe to retry — you cannot be billed twice for one intention.
A reused key with a different request#
The fix is always the same: use a new key for a new request.
How long a key is remembered#
Long enough for any realistic retry, and the detail you need is that it is bounded rather than forever. A key reused after the window is treated as new — which is another reason to generate one per operation rather than reusing a constant.
Without a key#
A call with no Idempotency-Key is simply charged. If it times out and you retry, you may be charged twice, because we cannot tell the retry from a second genuine request. For anything that costs real money, send a key.