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,
429and5xx. A4xxneeds 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.