Idempotency

All AstroWay API endpoints are naturally idempotent: same input always produces same output, no side effects (except credit consumption and usage logging).

This means retrying on network errors is safe. But to ensure a retry doesn’t charge credits twice, pass an Idempotency-Key header.

How to use

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "date": "1990-07-14", "time": "14:30:00", ... }

Idempotency-Key — arbitrary string up to 64 characters, unique per logical operation. Recommended: ULID or UUID v4.

Guarantees

• For 24 hours after the first request with a given key, repeat requests with the same key return the same response without recalculation and without charging credits.
• If the request body differs from the original — returns 409 Conflict with code idempotency_key_reuse.
• After 24 hours the key is forgotten; a new request with the same key is treated as a normal new request.

Note

Idempotency protects against double-charging on network failures, not caching. For caching, use the built-in X-Cache mechanism (5 minutes — see Credits & Rate Limits).

When you need it

• In webhook handlers where retries come from an external system (e.g. a payment provider or CRM sending events you parse and use for a calculation)
• In background jobs where retry is standard behavior on failures
• In CI/CD pipelines where a test may run multiple times

For normal “user clicks a button → show a chart” flows, idempotency isn’t needed — the user sees the result anyway, repeat clicks are rare.

When not to use

• Don’t set the key to save credits on identical requests — use X-Cache for that (free, 5 minutes)
• Don’t generate the key from hash(body) — you’d lose the default Idempotency-Key behavior (repeat 409 on body mismatch)