Retrying safely

Some calls must not run twice, such as buying a run pack or wiping a device. They accept an Idempotency-Key header, and their entries in the API reference say so. Pick a unique value for each change you mean to make. A UUID works well. Send the same value when you retry:

curl -X POST https://app.stockshift.io/api/v1/integrations/connections/01J8QZ4M.../channel/stock/push \
  -H "Authorization: Bearer $STOCKSHIFT_TOKEN" \
  -H "Idempotency-Key: 0199f2d4-6b1e-7c3a-9a51-2f0e8c1d4b7a"

A repeat within 24 hours gets the first response back without the change happening again, so a retry after a timeout is safe. Sending a key you already used on a different call answers 422 with idempotency_key_reused.

How the SDKs retry

The SDKs retry a 429 after Retry-After for every method, because the API did not run the call. They retry a 5xx or a network failure for GET, PUT and DELETE. A POST or PATCH is retried only when you give it an idempotency key:

await stockshift.post("/integrations/connections/{connection}/channel/stock/push", {
  path: { connection: connectionId },
  idempotencyKey: crypto.randomUUID(),
});

Get started

Using the API

Events and apps

How the SDKs retry

​How the SDKs retry

How the SDKs retry