Skip to main content

Operational safety

This page describes the integration rules that prevent double charges, lost usage, and hard-to-debug incidents.

Idempotency (MUST for writes)​

  • All write endpoints require Idempotency-Key (see OpenAPI for exact requirements).
  • If a write times out, retry the same request with the same Idempotency-Key and the same body.
  • Never reuse an idempotency key for a different logical operation.

Retries​

Use bounded retries with exponential backoff:

  • Retry on transient transport errors and 429.
  • Do not blindly retry on 4xx validation errors.

Timeouts​

Set explicit client timeouts and treat timeouts as "unknown outcome":

  • Retry via idempotency replays.
  • Avoid creating a second write with a different idempotency key.

Traceability​

Set X-Request-Id in your backend and propagate it to Vluna. Log it on both sides.

Hints​

hints are machine-readable signals that may appear on success or failure responses. At minimum:

  • log them
  • emit metrics
  • implement a policy for degradations (soft-deny, queue, lower quality) vs hard-deny

Next​