Retries and Idempotency
Every write is safe to retry. There is no Idempotency-Key header. Creates use a reference you supply, and state changes return the current state when repeated.
Create a Batch
Send externalReference when you might retry. It is unique within your organization, and test and live references are separate. A repeat create returns 409 with existingBatchId. Use that ID. The reference stays reserved after the batch is deleted.
Without externalReference, each retry creates another empty batch. Unsubmitted batches are cancelled after 7 days.
Retry Outcomes
| Request | Repeated With | Result |
|---|---|---|
| Create a batch | Same externalReference | 409 with existingBatchId |
| Add documents | Same references and checksums | 200 with the existing documents |
| Add documents | Any change | 409. Nothing in the request is added |
| Upload content | Same bytes | 200 |
| Upload content | Different bytes | 409 |
| Submit or cancel | Batch already in that state | 200 with the batch |
| Submit or cancel | Batch in another state | 409 |
| Delete a batch | Any repeat | 204 |
Request IDs
Every response includes a Request-Id header. Include it when you contact support.