Retries and idempotency

Networks fail. If a request to create an invoice times out, you can’t tell whether the invoice was created. Retrying blindly could create it twice; not retrying could lose it. Idempotency keys solve this.

How it works

Send a unique Idempotency-Key header with every POST and PATCH:

curl https://api.brrndops.com/v1/invoices \
  -H "Authorization: Bearer $BRRNDOPS_API_KEY" \
  -H "Idempotency-Key: 6f2b7c1e-4d3a-4b8e-9a1f-0c2d3e4f5a6b" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

If you retry with the same key and the same request, Brrndops doesn’t run it again. It returns the original response, with the header Idempotent-Replayed: true.

You send	You get
A new key	The request runs normally
The same key and the same request, after it finished	The original response, replayed
The same key while the first request is still running	409 request_in_progress. Wait and retry.
The same key with a different request	422 idempotency_key_reused

Keys are scoped to your API key and remembered for 24 hours.

Recommended retry strategy

1. Generate a key (a UUID works well) before the first attempt, and store it with the work you’re doing, for example on your order.
2. On a network error, timeout, 409, 429 or 5xx, retry with the same key.
3. Back off between attempts: 1s, 2s, 4s… up to a minute.
4. On other 4xx errors, don’t retry: fix the request first. A corrected request needs a new key.

Note

Server errors (5xx) aren’t stored, so retrying them with the same key runs the request again. That’s safe, because a request that failed with a server error didn’t complete.

GET and DELETE are naturally safe to repeat, so they don’t need a key.