Idempotency

• POST /v2/orders — buy a credit pack.
• POST /v2/surveys/{id}/publish — pay for and publish a draft survey.

​

The key

Idempotency-Key: 5f8b1c3e-4a7d-4a4c-9b0f-3f7c1a5b2c9d

• Up to 255 characters. A UUID or a hash of your own request identifiers both work.
• Scoped per team. Two different teams can reuse the same key without collision.
• Retained for 24 hours after the first attempt.
• Generate a fresh key per attempt. Reusing a key is only correct when the request body is byte-identical and you want the same server response.

​

Replay behaviour

• If the original succeeded (2xx), you get the exact same 2xx body back, with Idempotent-Replayed: true in the response headers.
• If the original returned an error, only the first response is stored — non-2xx responses are not replayed. Retrying is a fresh attempt.

​

402 on publish never binds the key

​

Credit-pack order retry guarantee

• The 24-hour window expires.
• You send a different body under the same key (which fails 409 idempotency_mismatch before charging anything).

​

Example

const idempotencyKey = crypto.randomUUID();

async function attemptPublish() {
  return fetch(`https://api.pickfu.com/v2/surveys/${surveyId}/publish`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      "Idempotency-Key": idempotencyKey,
    },
  });
}

// Safe to retry the exact same call on network error — the server will
// either replay the original 2xx or continue the in-flight attempt.
let res = await attemptPublish();
if (res.status === 409) {
  const { error } = await res.json();
  if (error.code === "idempotency_in_flight") {
    await new Promise((r) => setTimeout(r, 2000));
    res = await attemptPublish();
  }
}