Skip to main content

Idempotency

Use the Idempotency-Key header when a client might retry the same validation request.

Idempotency-Key: vat-async-2026-05-12-001

When the same key is reused with the same payload, the API returns the existing validation run instead of starting duplicate work.

When the same key is reused with a different payload, the API returns:

409 Conflict

Example​

curl -X POST "https://app.optimussoftware.de/api/v1/integration/vat/validations/async" \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: vat-async-2026-05-12-001" \
  -H "Content-Type: application/json" \
  -d @validation-request.json

Use stable keys from your system, such as an import job ID or batch ID, when retry safety matters.

If a create request fails or times out after the server accepted it, retry the same request with the same idempotency key. If you need to inspect the run later and you kept the key, call:

GET /api/v1/integration/vat/validations/by-idempotency-key/{idempotencyKey}

Key Guidelines​

  • Use one key for one logical validation request.
  • Reuse the same key when retrying the same request after a timeout, network failure, or client restart.
  • Use a new key when the request payload changes.
  • Store the key with your own import job, batch, or document record.
  • Do not use timestamps alone if the same job can be retried with a new timestamp.

For CLI users, Integration CLI creates and stores idempotency keys automatically in the saved state file. API clients need to send and store their own keys when retry safety matters.