Idempotency

Network failures can leave a client unsure whether an invoice was issued. Add an Idempotency-Key header when issuing an invoice to make the request safe to retry:

POST /v1/invoices
Authorization: Bearer ak_...
Idempotency-Key: 2f294ef2-9a60-4c7e-a573-5e18fa8348e2
Content-Type: application/json

Idempotency keys are optional. Without one, each request is treated as a new invoice issuance.

Generate a unique key for each intended operation. UUID version 4 values are a good choice. Keys may contain at most 255 bytes and should not contain customer data or other sensitive information.

Retrying a request

If a connection fails or times out, repeat the request with the same key and exactly the same parameters. Once the original request completes, FiscalRail returns its original status and response body. Replayed responses include:

Idempotent-Replayed: req_14Vxtqg6oXpAY5WdWoq4wW

The header value is the Request-Id of the original request whose result is being returned. The replay itself receives a new Request-Id.

Keys are scoped to the authenticated account. Within that account, a key identifies one operation and one set of parameters. Reusing it for a different operation or parameters returns 409 idempotency_key_mismatch.

If the original request is still executing, FiscalRail immediately returns 409 idempotency_key_in_use. Wait before retrying the same request. FiscalRail does not hold the second request open.

Requests rejected before invoice issuance, including invalid invoices, do not retain the idempotency key. Correct the request and submit it again with a new key.