Skip to main content

Idempotency

Write operations (POST, PUT, DELETE) require an Idempotency-Key header so you can safely retry a request without performing the operation twice. This matters when a network error leaves you unsure whether the first attempt succeeded. A write without the header is rejected with 400 invalid_request.

How it works​

  1. Generate a unique key per logical operation (a UUID works well).

  2. Send it on the request:

    curl -X POST https://app.toolpath.com/api/public/v0/parts \
      -H "Authorization: Bearer tp_live_xxxxxxxxxxxx" \
      -H "Idempotency-Key: 5f3c9b2a-..." \
      -H "Content-Type: application/json" \
      -d '{ ... }'

  3. Retry the exact same request with the same key: you get the original status code and body back instead of creating a duplicate.

Same key, different body

Reusing a key with a different request body returns 409 Conflict. A given key is bound to the first payload it saw.

Scope and retention​

  • Keys are scoped to the API key + endpoint path: the same Idempotency-Key value can be reused on a different endpoint (or by a different API key) without colliding.
  • Keys are retained for 24 hours. After that, the same key is treated as a brand-new request, so don't recycle keys, and don't rely on replays beyond the retention window.
  • A replayed response returns the original status code and body, but not the original response headers (e.g. Location). Read the resource id from the body rather than the Location header if you retry.

When to use it​

  • Always, on any write you might retry (and the API enforces this: writes fail without the header).
  • GET requests are already safe to repeat and ignore the header.