Skip to content
RobinReturn (opens in a new tab)
Partner API

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 sendYou get back
A fresh keyThe batch is processed normally
The same key with the same body, within about 10 minutesThe original response, replayed — the same status and the same created[] and rejected[]. The batch is not run again
The same key with a different body422 — 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 finished409 — 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.json

Sending 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

  1. Retry with the same Idempotency-Key. Within the replay window you get the original answer.
  2. 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.created events on a registered webhook endpoint, each carrying data.caseId and data.reference.
  3. If you resubmit under a new key, cases that were already created come back as DUPLICATE with existingReference, 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.