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 call | The repeat | Charged again |
|---|---|---|
| Still opening the file | 409 idempotency_key_in_use. Retry shortly with the same key to receive its result. | No |
| Reading, sync or async | 202 with the document, status processing. Poll GET /api/v1/documents/{id} or wait for the webhook. | No |
| Succeeded | 200 with the document as it stands now, and Idempotent-Replayed: true. | No |
Accepted with async=true | The 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 failed | Runs fresh. A call that returned an error gives its key back. | Only if this attempt succeeds |
| Succeeded, but the document was deleted since | 409 idempotency_key_not_replayable, reason: "expired", with the documentId. | No |
| Succeeded, more than 24 hours ago | 409 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.
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#
| Header | Meaning |
|---|---|
Idempotent-Replayed: true | The body is the stored document. Nothing was read or charged. |
X-Billable-Pages | The pages billed for the document. On a replay it repeats the original call's figure; the replay itself is not billed. |