Idempotency keys and safe retries

Retries are inevitable, since a timeout doesn't tell you whether the run was created. Nexis makes run creation idempotent so a retried request lands on the same resource instead of a duplicate. Apply the same discipline anywhere you accept a side-effecting delivery, like a webhook receiver.

Reuse the key, not the request

const run = await client.createRun({  prompt: 'Research Base liquidity and produce a report',  idempotencyKey: crypto.randomUUID(),});

• Generate the idempotencyKey once per logical run and hold onto it client-side before the request goes out, not after you see whether it succeeded.
• If POST /v1/runs times out or drops before you see a runId, retry with the exact same idempotencyKey. The BFF treats it as the same run, not a duplicate.
• Mint a new key only when you mean to start a genuinely new run. Reusing a key across unrelated prompts collides with the original run.

Know what idempotency does not cover

Apply the same discipline to inbound webhook deliveries

• Verify the signature against the raw request body before parsing it as JSON.
• Deduplicate deliveries by delivery identifier before applying any side effect. Treat the delivery id as the webhook equivalent of an idempotency key.
• Return a successful response only after durable acceptance, and reconcile from canonical resource state, since delivery can arrive out of order under retry.