Idempotency

Networks fail after the work is done. An idempotency key lets you retry a paid POST and get the original answer back instead of a second charge.

How it works

Add an Idempotency-Key header to any POST. Use a fresh random value per logical operation (a UUID is ideal) and reuse the same value on every retry of that operation.

curl

curl https://api.helixhumancapital.in/v1/match \
  -H "Authorization: Bearer $HELIX_KEY" \
  -H "Idempotency-Key: 5b0c2b7e-8f3a-4c43-9d57-0e9f1a2b3c4d" \
  -H "Content-Type: application/json" \
  -d '{"jobDescription": "…", "limit": 10}'

Python (requests)

import uuid, requests
idem = str(uuid.uuid4())
r = requests.post("https://api.helixhumancapital.in/v1/match", json=body, timeout=60,
                  headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": idem})

Node.js (fetch)

const idem = crypto.randomUUID()
const r = await fetch("https://api.helixhumancapital.in/v1/match", {
  method: "POST",
  headers: { Authorization: `Bearer ${KEY}`, "Idempotency-Key": idem, "Content-Type": "application/json" },
  body: JSON.stringify(body),
})

Rules

Situation	Result
Same key, same body, earlier request finished	The stored response is returned with `x-idempotent-replay: true` and `x-credits-charged: 0`.
Same key, same body, earlier request still running	`409 request_in_progress` with `Retry-After`. Wait, then retry. A request stuck for more than 2 minutes is taken over.
Same key, different body	`422 idempotency_key_reused`. Never a silent replay of the wrong answer.
Key shorter than 8 or longer than 200 characters	`400 invalid_idempotency_key`
Earlier attempt ended in 5xx, 402, 429 or 503	Not stored, so the retry really runs (and is charged only if it succeeds).

Keys are scoped to your API key. Two customers can use the same value without clashing.
Results are kept for 24 hours.
It applies to every POST: search, match, fit, parse, checkout. GETs are naturally safe to repeat.

← PreviousRate limits and errors Next →Webhooks