Idempotency

Ensure safety and reliability in your tax operations by preventing duplicate transactions using idempotency keys.

Why Use Idempotency?

Network failures or timeouts can lead to uncertainty about whether a request was processed. Idempotency allows you to retry a request safely without worrying about double-charging your wallet or creating duplicate filings.

The Idempotency Key Header

To perform an idempotent request, provide a unique string in the Idempotency-Key header. We also support the X-Idempotency-Key variant.

Expiration

Keys are stored for 7 days. Retrying an identical request within this window will return the exact same response from the cache.

Scope

Currently supported on PIT/CIT calculations and Filing submissions. Queries (GET requests) are idempotent by nature and do not require keys.

Bash (Example)

curl -X POST "https://pioe.app/api/v1/tax/file-pit" \
  -H "X-API-Key: tp_live_..." \
  -H "Idempotency-Key: pit_filing_2024_0102_user123" \
  -H "Content-Type: application/json" \
  -d '{
    "calculationId": "k17abc123xyz",
    "taxYear": 2024,
    "taxDue": 1050000,
    ...
  }'

Best Practices

Use UUIDs

We recommend using UUID v4 or high-entropy random strings to ensure uniqueness across your requests.

Same Context

Idempotency is scoped to the specific endpoint. Using the same key for a calculation and a filing will not cause a conflict.

Handling Retries

When you receive a timeout or 5xx error, retry with the *same* Idempotency-Key. If you change the key, it will be treated as a new request.

Ready to build?

Implementation of idempotency keys is highly recommended for all production B2B integrations involving financial flows.

Recommended