pub struct RateWindow {
pub used_percent: f64,
pub raw_used_percent: Option<f64>,
pub resets_at: Option<String>,
pub window_minutes: Option<i64>,
pub window_kind: Option<String>,
pub used_count: Option<f64>,
pub total_count: Option<f64>,
pub regeneration: Option<Regeneration>,
pub breakdown: Option<UsageBreakdown>,
}Expand description
One rate-limit window: how much of a quota pool is spent and when it resets.
Fields§
§used_percent: f640..100 percent of the window’s quota consumed. This is the EFFECTIVE
number consumers pace on: when banked-reset relaxation applies it is
zeroed, and the provider-reported percent moves to raw_used_percent.
raw_used_percent: Option<f64>The provider-reported percent when used_percent has been relaxed to
an effective value (banked resets guarantee the window resets before
the wall).
Pace on used_percent, not on this. The effective number is the real
headroom: a reset that is going to happen has already been accounted for.
Treating this as the truer figure routes work away from an account whose
credit is about to be spent — and the credit expires whether or not it is
used, so the cautious-looking reading is the lossy one. Display it beside
the effective number in a human-facing view, where a zero next to real
consumption would otherwise look like a fault.
Emitted only where the two diverge, so its absence means they agree
and falling back to used_percent is exact rather than approximate.
Rendering a placeholder for absence would be wrong on every unrelaxed
window, which is nearly all of them.
resets_at: Option<String>ISO 8601 / RFC 3339 timestamp when the window resets. Omitted when the provider reports no reset (e.g. an idle session window with nothing pending) — never fabricated.
window_minutes: Option<i64>Window length in minutes. Omitted when the provider does not report one; the consumer then paces on utilization alone rather than a burn rate.
window_kind: Option<String>The period this window covers, when the upstream names it: one of the
values in window_kind, or a value a consumer has not seen yet.
It exists for windows whose length cannot be stated in minutes. A month
varies, so a monthly window carries no window_minutes, and without a
name a consumer cannot tell it from any other window with no stated
length, or from whatever a provider’s other page shape puts in the same
slot. The first reader matches a refusal that names its limit (“monthly
usage limit reached”) to the window it refers to.
Absence means the upstream did not name the period, never “some other
kind”. A producer sets it only from the upstream’s own label or field (a
page’s “Monthly usage” heading, an API key such as seven_day), mapped
onto this vocabulary. A consumer that needs the period of an unnamed
window falls back to window_minutes.
An open string, not an enum: an unknown kind must reach the consumer intact, not fail the decode of the whole response.
used_count: Option<f64>Absolute consumed count in the window (e.g. tokens, requests). A count of things, so integral by contract, and only ever the upstream’s own figure — never recovered from a percentage and a cap (a derived figure can carry a disagreement between two provider endpoints while wearing a type that claims exactness). Omitted when the upstream reports only a percentage. Human-facing UIs can show “10,336 / 40,000” alongside the percentage for richer context.
total_count: Option<f64>Absolute total cap for the window, when the upstream states one. May
appear without used_count: the cap can be known while the consumed
figure is only a percentage.
regeneration: Option<Regeneration>How the window’s quota comes back, when the upstream STATES a mechanic.
Absence licenses nothing. It means the upstream said nothing about replenishment — never “this is a fixed window”. Most providers state nothing, so absence is the common case and carries no information.
breakdown: Option<UsageBreakdown>How the window’s consumption divides among the upstream’s own categories, when the upstream states that split.
Absence means not fetched or not published, never “all zero”. Most providers state no split, so absence is the common case.