akwitoEU VAT proof

Documentation / Getting started

Idempotency

POST /v1/checks accepts an Idempotency-Key header, 1 to 255 visible characters. It is stored before the request is processed, so a client that repeats the same key — after a timeout, a retry, a crash — always gets the exact same response instead of creating a second check:

  • Replay. The same key comes back with the first response, unchanged, and the header X-Akwito-Idempotent-Replay: true. It is a 200 with the check when the first call finished with a check; a 202 with the pending request re-read from the store, so status reflects where it is now, while it is still pending; and, once a first call accepted with 202 has since reached done or failed, a 200 carrying that request's current state — the same shape as GET /v1/requests/{id}, check_id and check included for done — rather than a 202 with no check_id.
  • 422 IDEMPOTENCY_MISMATCH. The same key is used with a different request body. The key remembers the first body's fingerprint, not just its presence: reusing it for anything else is refused, not silently replayed.
  • 409 IDEMPOTENCY_IN_PROGRESS. The first request with this key is still running. Carries retry_after: 1.
sh
curl -s -i -X POST https://api.akwito.eu/v1/checks -H "Authorization: Bearer ak_live_…" \
  -H "Idempotency-Key: invoice-2026-0417" -H "Content-Type: application/json" \
  -d '{"vat_number":"FR40303265045","reference":"F-2026-0417"}' | head -1
# HTTP/1.1 201 Created

curl -s -i -X POST https://api.akwito.eu/v1/checks -H "Authorization: Bearer ak_live_…" \
  -H "Idempotency-Key: invoice-2026-0417" -H "Content-Type: application/json" \
  -d '{"vat_number":"FR40303265045","reference":"F-2026-0417"}' | grep -E "^HTTP|X-Akwito-Idempotent-Replay"
# HTTP/1.1 200 OK
# X-Akwito-Idempotent-Replay: true

A 4xx or 5xx response releases the key: only a request that actually produced something (a check, or a pending request) is remembered. The key lives 24 hours; past that, the same value can be reused for a new request.

Idempotency-Key only applies to POST /v1/checks.

Versus deduplication. The 24 hour deduplication described above is a business rule keyed on the VAT number, mode and reference: it can still return a 200 for a request that never carried an Idempotency-Key. The header is a stricter, separate guarantee — the exact same response, byte for byte, and a refusal (422) rather than a silent match when the body differs.