Skip to content
DocsGuides

Idempotency and retries

Send an Idempotency-Key header on every POST and retries are safe. A repeat of a call that succeeded returns that document instead of reading the file again.

One key per document#

Any unique string; a UUID is fine. Generate it once for a document and reuse it for every attempt, including attempts after a timeout where you never saw a response.

Keys are scoped to the mode that used them. The same string can be used once with a test key and once with a live key, and neither replays the other.

What a repeat does#

State of the first callThe repeatCharged again
Still opening the file409 idempotency_key_in_use. Retry shortly with the same key to receive its result.No
Reading, sync or async202 with the document, status processing. Poll GET /api/v1/documents/{id} or wait for the webhook.No
Succeeded200 with the document as it stands now, and Idempotent-Replayed: true.No
Accepted with async=trueThe document as it stands: 202 while processing, 200 once finished. A read that later failed replays with status: "failed"; send a new key to try that file again.No
Refused, or a synchronous read that failedRuns fresh. A call that returned an error gives its key back.Only if this attempt succeeds
Succeeded, but the document was deleted since409 idempotency_key_not_replayable, reason: "expired", with the documentId.No
Succeeded, more than 24 hours ago409 idempotency_key_not_replayable, reason: "expired", with the documentId.No

A retry can never read the file a second time while the first attempt is running, so a client timeout shorter than the read is safe: retry with the same key until the document comes back.

Retrying#

While a document keeps failing, every attempt runs fresh and none of them cost anything. Retry 429, 5xx and 409 idempotency_key_in_use with backoff and the same key.

import { randomUUID } from "node:crypto";

// One key per document, reused by every attempt. A new key on a retry
// is a new document, and is charged as one.
async function parse(pdf, { key = randomUUID(), attempt = 1 } = {}) {
  const res = await fetch("https://statementbear.com/api/v1/documents", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.STATEMENTBEAR_KEY}`,
      "Content-Type": "application/pdf",
      "Idempotency-Key": key,
    },
    body: pdf,
  });

  if (res.ok) return res.json();

  // Retry 429 (concurrency), 5xx, and a key whose first call is still running.
  const { error } = await res.json();
  const retryable =
    res.status === 429 || res.status >= 500 || error.code === "idempotency_key_in_use";
  if (!retryable || attempt >= 4) throw new Error(`${error.code}: ${error.message}`);

  await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
  return parse(pdf, { key, attempt: attempt + 1 });
}

The 409#

A key is held for 24 hours. A repeat after that, or after the document was deleted, returns 409 idempotency_key_not_replayable instead of reading the file again, which would charge a second time for one call. The error carries documentId: while the document exists, fetch it with GET /api/v1/documents/{id}. Use a new key only if you want the file read and charged again.

Response headers#

HeaderMeaning
Idempotent-Replayed: trueThe body is the stored document. Nothing was read or charged.
X-Billable-PagesThe pages billed for the document. On a replay it repeats the original call's figure; the replay itself is not billed.
Something wrong or missing on this page? [email protected]