​
What Are Idempotency Keys?

Idempotency keys allow clients to safely retry API requests without the risk of performing the same operation multiple times. This is especially useful in cases of network issues, timeouts, or client-side retries where duplicate API calls could lead to repeated billing or unexpected behavior.

​
Applicable Endpoints

Idempotency keys are supported (but not enforced) for the following paid endpoints:

  • POST /v1/tax/rate
  • POST /v1/tax/id-validate
  • POST /v1/tax/unify

These endpoints are billable per request. Using an idempotency key helps avoid duplicate billing in case the same request is sent more than once.

​
How to Use

Send a unique key in the request header (see example below).

Idempotency-Key: <your-unique-key>
  • The key must be a string (typically a UUID or unique hash).
  • If a request with the same key has already been processed, the original response will be returned — without executing the request again.
  • Keys are scoped per endpoint and expire after a short window (e.g., 24 hours).

​
Best Practices

  • Always generate a new key for each new operation.
  • Use the same key when retrying the same request due to a timeout or failure.
  • Avoid reusing the same key across unrelated requests.

​
Why It Matters

  • Prevents accidental duplicate billing or tax calculations
  • Ensures network resilience during intermittent errors
  • Supports auditability and traceability for financial operations

Idempotency keys help reduce cost exposure and improve reliability — especially when working with paid, compute-heavy APIs. While optional, we strongly recommend using them in all production requests to ensure safe and efficient API behavior.