GetbeelDocs

Idempotency

Safely retry requests that create or send invoices with the Idempotency-Key header.

A flaky network can lose the response to a request that succeeded. Retrying it blindly could create two drafts or, worse, send the same invoice twice. The Idempotency-Key header prevents that.

How it works

Send a unique value (we recommend a UUID v4) in the Idempotency-Key header of every POST that creates or sends:

curl -X POST https://www.getbeel.com/api/v1/invoices/INVOICE_ID/send \
  -H "Authorization: Bearer $GETBEEL_API_KEY" \
  -H "Idempotency-Key: 9f1c2a4e-7b3d-4e8a-a1f2-3c5d7e9b0a12"
  • The first request with a key runs, and its response is stored for 24 hours.
  • If you repeat the same request with the same key, you get the stored response and the operation does not run again.
  • If you reuse the key for a different request (another endpoint or body), you get an error instead of a wrong response.

It applies to POST /invoices and POST /invoices/{id}/send.

Good practice

  • Generate the key when you decide to perform the operation and store it with the operation, so a retry after a crash reuses it.
  • Use a new key for every distinct operation: two invoices, two keys.
  • Retry only network errors, 429 and 5xx. A 4xx needs fixing, not retrying.

The errors: 409 idempotency_key_in_use (a request with the same key is still running: retry shortly with the same key), 422 idempotency_key_reused (key already used for a different request: use a new one), 400 parameter_invalid with param: "Idempotency-Key" (the key must be 1–255 visible ASCII characters). See Errors.

Even without a key, a draft is sent only once: a second send gets 409 invoice_send_in_progress or 409 invoice_not_draft before any call to SDI. See SDI lifecycle.

On this page