Rules›northwind-missing-idempotency-key

northwind-missing-idempotency-key

info

northwind/reliability/missing-idempotency-key

Docs page ↗

charges.create is called without the idempotencyKey request option, so a retry — by the SDK, a proxy, or an impatient user — creates a second charge.

15

codebases affected, of 58

26%

of everything we scanned

—

no docs fix scored yet

1

docs commits aimed at this

Where it’s failing

charges.create is called without an idempotencyKey request option.

what we find

what we change it to

await northwind.charges.create({
amount: order.totalCents, currency: 'usd', customer,
})
// timeout → job retries → the buyer pays twice
await northwind.charges.create(
{ amount: order.totalCents, currency: 'usd', customer },
{ idempotencyKey: `order-${order.id}` },
) // a retry returns the original charge

Pass a stable key derived from the thing being paid for: northwind.charges.create(params, { idempotencyKey: "order-" + order.id }). Reusing the key returns the original charge instead of creating another.

Metadata

Category
reliability
Type
suggestion
Severity
info
Recommended
yes
Languages
javascriptpython

Live telemetry

15 / 58 scans

Fired in 26% of scanned codebases.

After every docs commit

docs(api): idempotency key in the create-a-charge example

9d2c05a · merged 2 weeks ago · PR drafted by api-doctor

24% → 19%▼5pts

A fix for your docs page

Wherever this rule fires, a page on your docs site taught it. api-doctor writes the edit and opens it as a pull request on your docs repo — you review and merge.

No fix yet

Draft a docs fix for this rule

api-doctor writes the docs change from the fire pattern — you review it

History

Active

Name the retried call in the lint message

1 week ago · via GitHub

f92e6c8
Superseded

Exempt charges created inside an explicit dedupe transaction

6 weeks ago · via GitHub

7c03da5
Superseded

Initial rule — charges.create without an idempotency key

12 weeks ago · via GitHub

20b4e79