Skip to main content

Preflight

POST /mgt/v1/gate/preflight previews the current admission result before an application starts work that is expensive or difficult to undo. It uses service auth and the same principal/user identity as the later authorize request.

Preflight accepts the authorize fields feature_code, optional feature_family_code, estimated_quantity_minor, budget, and labels. It does not accept lease and does not require Idempotency-Key.

Guarantees and limits​

Preflight and a new authorization lifecycle share the same entitlement, billing-mode, funding, quota, rate, Budget, policy, and pricing decision path. Preflight changes the effect mode of that path:

  • it does not create or update a lease or idempotency envelope;
  • it previews rate counters instead of consuming them;
  • it does not reserve wallet or Budget value;
  • it disables feature and meter auto-registration;

Preflight uses the same standard runtime identity resolution as authorize. That resolution may idempotently provision a missing billing account or user. Identity provisioning is an authentication/runtime normalization step; it is not an admission, metering, or billing-resource mutation.

The allow response has as_of, feature/family, and policy window bounds, but no lease. Rejections reuse authorize HTTP statuses, envelope codes, metadata, and hints. Every success or business/configuration denial that enters the admission evaluator uses one shared evaluation instant: success returns it as data.as_of, and denial returns it as meta.as_of. Authentication, scope, or request-shape errors rejected before evaluation may omit as_of.

The result is advisory. Configuration, balance, budgets, counters, and other concurrent requests can change before authorize. Always run the normal authorize → operation → commit flow for the real operation.

Unknown features are the documented parity exception: preflight returns a read-only configuration failure, while authorize may auto-register the feature when that deployment option is enabled.

Hint handling​

Treat HTTP status, ok, and envelope code as authoritative. Success hints such as funding.xusd_shortfall, quota.remaining, or rate.limit are advisory; a hint alone is not a denial.