Skip to content

Idempotency

Send a write twice without applying it twice, with the Idempotency-Key header.

Version v1.1, updated

On this page

A network can fail after BIRP applied a write but before you read the answer. The Idempotency-Key header lets you send the same write again and get the first answer back, without a second record.

When to send it

  • Every POST must carry Idempotency-Key. Without it the answer is 422 idempotency_key_missing.

  • PUT, PATCH and DELETE take it too, and we recommend it on every write.

  • The value is 1 to 128 visible characters, unique to one request. A new UUID per request is the simple choice.

What happens on a retry

You send

BIRP answers

The same key, path and body, within 24 hours

The stored answer, with Idempotency-Replayed: true. Nothing is written twice.

The same key on the same operation, with another body or another record

422 idempotency_key_reused.

The same key on another operation

A separate request: a key applies to one operation.

The same key while the first request still runs

409 idempotency_in_progress. Retry after a short wait.

The same key after 24 hours

A new request, as if the key had never been used.

Keys belong to your company: another company can use the same value with no effect on yours.

What is replayed

Only a successful answer is replayed. After an error, fix the cause and retry with the same key: the request runs again.

Batches

A batch takes one key for the whole request. A replay returns the stored result of every item, even the items that failed. To retry only the failed items, send them in a new batch with a new key.

Retry safely

  1. Create the key once, before the first attempt, and store it with the work to do.

  2. On a timeout, a network error or a 5xx, send the same request with the same key.

  3. On a 4xx other than 409 idempotency_in_progress, fix the request: retrying it unchanged gives the same error.

Related

  • handling-errors
  • batches
  • requests