Skip to main content
Network failures can leave you unsure whether a request succeeded. ProxyJam supports idempotency on create operations so you can retry safely.

​
How it works

Include a unique idempotency_key (UUID) in your request body. If you send the same key again, the API returns the original response instead of creating a new resource.

​
Endpoints that support idempotency keys

​
Header-based idempotency

Some endpoints take the idempotency key as the HTTP Idempotency-Key header rather than a body field:
The Idempotency-Key header is required for POST /payments/payment-intents and for mobile-rotating calls to POST /orders/{order_id}/extend. Requests will be rejected without it.
A replay with the same key returns the stored response verbatim — the same body you got the first time, down to fields that describe how that first call went. On POST /ip-check, for instance, a replay repeats the original charge and cached values rather than recomputing them, because it is reporting what happened, not what would happen now. Sending a different payload with a key you have already used answers 409 with error.code of CONFLICT. Keys are matched against a hash of the request, so this is detected even when the difference is a single character.

​
How long a key stays replayable

Stored responses are kept for a limited window — at least 30 days from the original request. Treat that as a floor, not a promise: do not build a flow that depends on replaying a key weeks later.
A replay sent after the window has passed is not recognised as a replay. It executes as a brand-new request — which, on a billable endpoint, means it charges again. Retries are for minutes and hours, not for months.
Nothing about this changes the guarantee inside the window. If you retry a failed or timed-out request within the ordinary lifetime of that operation, the key does exactly what it says.

​
Best practices

  • Generate a new UUID for each unique operation. Never reuse a key for a different operation.
  • Store the key before making the request so you can resend it on retry.
  • Keys are scoped per user — the same key used by two different users creates two separate resources.