SATIK DEVELOPER DOCS · V1 BETA

Retry safely with idempotency keys.

Send one operation, recover its result, and avoid duplicate verification work.

What an idempotency key does

An idempotency key is an optional retry label created by your application before sending an operation. If a connection drops after Satik processes the request, retry with the same key and unchanged body to retrieve its saved response instead of creating another verification. Supported on POST /v1/addresses/verify and POST /v1/addresses/verify/batch.

Send a verification with a key

Set SATIK_KEY to your live API key on your server. Generate a unique label once for this operation and keep it for retries. The example below uses an illustrative label; use a fresh one for each new operation. This custom address requires a live key and the first successful request consumes verification quota. For localhost, replace the URL with http://localhost:3001/api/v1/addresses/verify.

curl --request POST 'https://api.satik.in/v1/addresses/verify' \
  --header "Authorization: Bearer $SATIK_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: verify-order-001-attempt-1' \
  --data '{
    "address": "Dak Bhawan, Sansad Marg, New Delhi 110001",
    "order_id": "POSTMAN-LIVE-001"
  }'

Retry the same operation

After a timeout or lost response, run the same request again with the same key and body. If the original operation completed, Satik returns its saved verification ID, verdict and other result fields, with meta.idempotent_replay set to true. It does not create a new verification log, call Google again or consume additional verification units. Authentication and rate limits still apply. The saved history and verdict describe the original operation, not a fresh check. This is a partial response illustration, not a predicted verdict.

{
  "id": "ver_72e72619-fba4-473d-85f3-c163e7524fc0",
  "order_id": "POSTMAN-LIVE-001",
  "meta": { "idempotent_replay": true }
}

Know which identifier to use

The idempotency key is not your API secret, workspace ID, order ID or verification ID. Satik implements retry protection; your application supplies the stable label that lets Satik recognize a retry.

Identifiers in a verification request
Identifier	Meaning
Idempotency-Key`verify-order-001-attempt-1`	Created by your application and sent with the request. Reuse only for retries of the same operation.
Verification ID`ver_72e72619-…`	Generated by Satik and returned as id. Identifies the verification result; use it as verification_id when reporting an outcome.
Order ID`POSTMAN-LIVE-001`	Your business reference. Keeping the same order_id does not deduplicate requests.
Tenant ID	Identifies your workspace and scopes retry keys and address cache records. It is not a ver_… identifier.

When to reuse or change the key

Generate the key before the first request, for example with a UUID in your backend, and persist it with the operation. Do not generate a new key inside every retry attempt.

Retry and conflict behavior
Situation	What to do
Same operation after a lost response	Keep the same key and unchanged request body. A completed operation replays its saved result.
Request still processing	HTTP 409 with error.code idempotency_key_in_use. Wait and retry the same request/key; do not change the key to bypass processing.
Same key with a different request body	HTTP 409 with error.code idempotency_key_in_use. Check the error message to distinguish a payload conflict from an in-progress request.
Corrected address or deliberate new check	Create a new key. You may keep the same order_id to associate the new verification with the original order.
No idempotency key supplied	Retry protection is not enabled for that operation. A repeat can create another verification, even when its address result comes from cache.

Key format, scope and lifetime

Use a non-empty string of at most 200 characters. Keys are scoped to the workspace, not to an individual API credential; choose distinct keys for different operations and endpoints. Prefixes batch-item: and internal: are reserved. Records expire after 24 hours from creation, so do not rely on the key to prevent duplicates beyond that window. Replays do not extend the window. Keep your own durable order/operation tracking for longer-lived deduplication.

Header or JSON body

The Idempotency-Key header is recommended for clarity. You can alternatively send an idempotency_key field in the JSON body. If both are supplied, a non-null body value takes precedence over the header; use one form consistently to avoid confusion.

{
  "address": "Dak Bhawan, Sansad Marg, New Delhi 110001",
  "order_id": "POSTMAN-LIVE-001",
  "idempotency_key": "verify-order-001-attempt-1"
}

Idempotency versus address caching

A retry repeats an operation; an address-cache hit reuses provider work for a new operation. The same address may belong to multiple orders, so an address should not be used as a permanent idempotency key.

Two different ways to reuse work
Path	Result
Completed idempotency replay	Same verification ID and saved result; no new verification log, Google call or additional verification quota.
Live address-cache hit	New verification ID and log, with current order_id and a history lookup; no new Google call. Consumes 0.1 verification units.
Live cache miss	Fresh provider validation, subject to availability and quota. A successful verification consumes 1 unit.