Guides

Idempotency for write requests

Safely retry POST requests without duplicating scans, properties, or batch jobs.

Overview

Write endpoints accept an optional Idempotency-Key header (max 128 characters). When you repeat the same key within 24 hours, the API returns the original successful response without running the operation again.

Covered endpoints include:

POST /properties
POST /properties/:id/scans and /crawls
POST /scans/batch
POST /properties/:id/gsc/sync
POST /webhooks

Example

curl -X POST \
  -H "Authorization: Bearer xf_live_..." \
  -H "Idempotency-Key: scan-2026-06-07-example-com" \
  https://api.xenonflare.com/api/v1/properties/PROPERTY_ID/scans

Replay behavior

Same key + same path + same org within 24h → cached 2xx response replayed (same data body).
Different request body with the same key → treated as a new request (key is scoped to the successful response that was stored).
Failed responses (4xx/5xx) are not cached — retry with the same key after fixing the error.

CI patterns

Use a stable key per pipeline run so network blips do not queue duplicate crawls:

# GitHub Actions — one scan per workflow run
IDEMPOTENCY_KEY="ci-${GITHUB_RUN_ID}-${GITHUB_SHA}"

curl -X POST \
  -H "Authorization: Bearer $XENONFLARE_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  $XENONFLARE_API_BASE/properties/$PROPERTY_ID/scans

For nightly cron, include the date: nightly-2026-06-07-propertyId so a second cron tick the same night does not enqueue twice.

When to retry

Status	Action
`429 rate_limit`	Wait until reset (see rate-limit headers or `GET /rate-limits`), retry with same key
`5xx internal_error`	Retry with exponential backoff; same idempotency key is safe
`400 validation_error`	Fix the request; use a new idempotency key after changing the body
`403 plan_required`	Upgrade plan or wait for quota reset — do not retry blindly

Create an API key

Use Idempotency-Key on write endpoints when building CI or webhook receivers.

Developer API access requires a Starter or Growth workspace. Free tier includes the web app and free marketing tools — not API keys.

Create API key in app API reference Developer settings →