Idempotency
How the Idempotency-Key header replays a Partner API batch on retry, when you get 409 or 422 instead, and how the per-invoice duplicate guard catches unkeyed retries.
Last updated
Send an Idempotency-Key header with every POST /api/v1/cases batch. If you retry the same
batch under the same key, RobinReturn replays the original answer instead of running the batch
again. Independently, a per-invoice duplicate guard stops a retry without a key from creating a
second case for the same invoice.
Idempotency-Key
Generate one key per batch, from the batch — for example a hash of the request body or your own job ID. Do not reuse a key per day, per file or per client session.
| You send | You get back |
|---|---|
| A fresh key | The batch is processed normally |
| The same key with the same body, within about 10 minutes | The original response, replayed — the same status and the same created[] and rejected[]. The batch is not run again |
| The same key with a different body | 422 — your key generation is not unique per batch. A new batch is never answered with an old batch's result |
| The same key while no answer has been recorded — the first request is still running, or it never finished | 409 — the key stays reserved for 24 hours |
The replay window is deliberately short, and an unusually large response is not stored at all, so treat a replay as a way to recover a request that timed out, not as a way to fetch a past result.
curl -X POST https://app.robinreturn.co.uk/api/v1/cases \
-H "Authorization: Bearer $RR_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: batch-2026-10-08-0001" \
--data @batch.jsonSending the same command again within the replay window returns the same response.
The per-invoice duplicate guard
Independently of the header, a case is rejected per case with code DUPLICATE when your company
already has a case for the same invoiceRef — a live case chasing it, or a DRAFT from an
earlier submission. The rejection carries existingReference, the reference of the case that
already holds the invoice. Closed, settled and withdrawn cases do not block.
So a retry without a key, or after the replay window, does not create a second case: each case
that was already created comes back as a DUPLICATE rejection instead. The match is exact and
case-sensitive on invoiceRef, with no trimming, so INV-001 and inv-001 are different invoices.
The guard checks before it writes, so it does not make two identical requests sent at the same time safe — both can pass the check. That is why the key still matters.
If you are unsure whether a request succeeded
- Retry with the same
Idempotency-Key. Within the replay window you get the original answer. - If you get 409, the first request has not recorded an answer. Do not resubmit straight away:
check the cases in the dashboard, or wait for the
case.createdevents on a registered webhook endpoint, each carryingdata.caseIdanddata.reference. - If you resubmit under a new key, cases that were already created come back as
DUPLICATEwithexistingReference, so nothing is created twice.
A case reported with code INTERNAL is one RobinReturn could not confirm. Resubmitting it is safe:
if it was created, the resubmission is rejected as DUPLICATE.
Clearing a draft that is blocking you
The Partner API has no endpoint that lists, deletes or withdraws a case. If a draft holds an
invoice reference you need to resubmit — a batch sent with the wrong amount, for example — sign in
to the dashboard, open the case named by existingReference, and withdraw it. The corrected
submission then succeeds.
The blocking draft is not always one the API created: a draft someone on your team started in the dashboard and abandoned blocks the same invoice reference, because the check is per company.