Hint contract
Hints are machine-readable policy signals returned by gate operations.
This page defines stable interpretation semantics for the main hint families.
Core families
Capacity and rate
quota.remaining: current admissible quantity is lower than requested or exhausted.rate.limit: current request exceeds rate window policy.
Funding and budget
funding.xusd_shortfall: account funding cannot cover expected or committed cost.budget.shortfall: selected budget cannot cover required amount.budget.low_headroom: request is allowed but budget headroom is low.
Policy and mapping integrity
policy.window_not_found: commit cannot find matching policy window context.feature.meter_not_allowed: submitted meters are not valid for the feature.
Pricing integrity
pricing.not_configured: one or more meters have no usable pricing.pricing.meter_price_missing: specific meter price missing for contract context.pricing.contract_term_invalid: contract term is present but invalid.pricing.changed: server-side pricing fingerprint differs from client expectation.
Lease state
lease.expired: commit happens after lease expiry (with grace metadata).lease.closed_at_commit: lease is no longer active when commit is attempted.
Client behavior contract
- Treat hints as control signals, not logs.
- Keep per-hint deterministic handling in product code.
- Differentiate:
- hard admission failures
- accepted-but-quarantined commit outcomes
- idempotent replay outcomes
Minimal action mapping
| Hint | Client action baseline |
|---|---|
rate.limit | retry with bounded backoff/jitter or queue |
quota.remaining | reduce quantity, split work, or block and upgrade |
funding.xusd_shortfall | prompt top-up/upgrade or degrade |
budget.shortfall | switch budget or replenish budget |
budget.low_headroom | warning state and proactive refill guidance |
feature.meter_not_allowed | correct payload mapping before retry |
policy.window_not_found | escalate config issue, do not blind-retry |
pricing.not_configured | treat as config gap, route to operators |
pricing.changed | refresh quote and re-confirm high-value actions |
lease.expired | restart authorize->commit path if beyond grace |
lease.closed_at_commit | fetch/replay prior result, avoid duplicate business effects |
Next
- Operational handling details: Hints and failure semantics