Skip to main content
Every order creation and position-close request must include an Idempotency-Key header. This includes POST /v1/orders, POST /v1/twap-orders, POST /v1/scaled-orders, and POST /v1/positions/{position_id}/close. Use a unique value for each intended operation and reuse that same value only when retrying the identical request on the same endpoint.
The key may contain printable ASCII characters and may be up to 128 characters. Funding Perpetuals binds it to the API key, endpoint, and a hash of the request. The binding is written in the same database transaction as the order, so two concurrent retries cannot create two accepted orders. The first accepted request returns 201 Created. A retry with the same key and payload returns 200 OK with the order’s current state. That state may have advanced since the first response, for example from pending to filled, so use the returned status as the source of truth. A trading-rule rejection returns 422 on both the original request and every matching retry. The error keeps the original order_id, rule code, and details, so a lost response cannot turn a rejected placement into an apparent success. Reusing an idempotency key with a different account, market, side, size, or other order field is rejected. Generate keys with enough entropy, such as a UUIDv4 or ULID, and retain them alongside your local order record.