Idempotency
A network error can hide whether a write ran. Send an Idempotency-Key
header with every write, and you can retry it safely.
POST /api/companies/{company_id}/invoices/{invoice_id}/issue HTTP/1.1
Authorization: Bearer osk_live_...
Content-Type: application/json
Idempotency-Key: 5f0c9a1e-6f0b-4c1e-9a52-2b8f0d5b7e41
{}- Use a new random key for each new change, for example a UUID. Use the same key only to retry the same request.
- The command operations and the file upload accept the header. The API reference lists it among the parameters of each operation that takes it.
What a repeat gets
| The repeat | The answer |
|---|---|
| The same key and the same body, after the first request finished | The first response again, with the header Idempotent-Replayed: true. Nothing runs twice |
| The same key and the same body, while the first request still runs | 409 idempotency_in_progress. Wait and retry |
| The same key with a different body | 409 idempotency_conflict. Use a new key for a new request |
- The API keeps a key for 24 hours, for each credential and company.
- Only a success is kept. After an error (a status of 400 or more), you may retry with the same key.
- When the first request died before it finished, the key is free again after five minutes, and a retry with the same body runs it. The books themselves also remember the key, so a command never runs twice.
Without the header
A write without an Idempotency-Key runs every time you send it. A retry
after a timeout can then record the same invoice twice.