Skip to content

Idempotency

A network timeout or error while submitting an invoice leaves you in an awkward spot: did the request reach the server and create the invoice, or not? Retrying blindly risks sending the same invoice to SDI twice.

To avoid this, the send endpoints accept the optional Idempotency-Key header.

How it works

Generate a unique client-side key (for example a UUID) and pass it in the Idempotency-Key header alongside your request:

curl -u "YOUR TEST API KEY (starts with ik_test_)": \
  -H "Idempotency-Key: 3f8c1e9a-7b21-4c0d-9f6e-1a2b3c4d5e6f" \
  -F "file=@path/to/file/filename.xml" \
  https://api.invoicetronic.com/v1/send/file | jq
  • The first request with a given key is processed normally and its response is stored.
  • Any retry with the same key returns the original response without creating a second invoice.

The key is valid for 24 hours: enough to cover realistic retries without becoming a permanent deduplication store.

Supported endpoints

The header is accepted on all send endpoints:

  • POST /send
  • POST /send/xml
  • POST /send/file
  • POST /send/json

The validation-only endpoints (POST /send/validate/*) don't need it: they don't create anything.

Behavior

Situation Response
First request with the key Processed normally; the response is stored
Retry with the same key and same content Original response replayed (no duplicate)
Request with the same key still in progress 409 Conflict
Same key reused with different content 422 Unprocessable Entity

The 409 protects against concurrent requests: if two twin submissions start together, one is processed and the other receives 409. The 422 protects against an integration mistake: an idempotency key must always identify the same request, so reusing it for a different invoice is treated as an error.

Best practices

  • Generate a new key for each distinct invoice and reuse the same key only when retrying the submission of the same invoice.
  • Keep the key on the client until you receive a definitive response, so you can safely retry after a timeout.
  • The header is optional: if you don't send it, behavior is unchanged.

Idempotency and rate limiting

A retry protected by Idempotency-Key still counts toward your rate limits. Replaying a stored response, however, is far cheaper than a fresh submission to SDI.