A network error after you submit a job leaves you not knowing whether it was queued. Retrying could start it twice, and pay twice. An Idempotency-Key header makes the retry safe: CogniChem remembers the key with the result, and a repeat with the same key returns that result instead of doing the work again.
The rules
- Send a new unique key (a UUID is ideal) for each distinct request, and the same key when you retry that request.
- API keys must send one on writes that start or save something: job, utility, and inference submits; workflow runs; saving, forking, restoring, and sharing workflow definitions; and uploads. Without it they get
400(missing-idempotency-key). - Approving an Assistant plan card needs a key from every caller, access tokens included. Other access-token writes may omit it.
- A repeat with the same key and the same body returns the first response for 30 days.
- The same key with a different body returns
409: keys are not reusable across different requests. - A repeat while the first request is still being handled also returns
409; wait a moment and retry. - Keys are up to 255 characters and are scoped to your account.
Don't derive the key from the request body: two jobs you meant to run separately would collide. Generate it once per logical request and keep it with your retry state.
KEY=$(uuidgen) # keep this for retries of this one submit
curl -X POST https://api.cognichem.com/api/v1/jobs/submit \
-H "X-Api-Key: $COGNICHEM_API_KEY" \
-H "Idempotency-Key: $KEY" \
-H "Content-Type: application/json" \
-d @job.jsonEndpoints that accept the header list it under Headers in the API reference. The Python SDK sends a fresh key on every write; pass idempotency_key= yourself to reuse one across retries. Retry safely shows a complete retry loop.