atuinsh/atuin · error

usage request failed ({status})

Error message

usage request failed ({status})

What it means

`fetch_usage` requests usage/quotas from the AI gateway and bails with the HTTP status when the response is not successful. Like the model-list fetch, it surfaces the raw status so the caller can tell auth failures from server errors.

Source

Thrown at crates/atuin-ai/src/usage.rs:106

}

/// Fetch current usage from the hub. Mirrors the `credits` object on the
/// chat `done` event, for refreshing without starting a chat.
pub async fn fetch_usage(endpoint: &reqwest::Url, token: &str) -> Result<UsageSnapshot> {
    let url = endpoint.append_path("api/cli/usage")?;

    let response = reqwest::Client::new()
        .get(url)
        .header(USER_AGENT, crate::stream::APP_USER_AGENT)
        .bearer_auth(token)
        .timeout(Duration::from_secs(10))
        .send()
        .await
        .context("failed to fetch usage")?;

    let status = response.status();
    if !status.is_success() {
        eyre::bail!("usage request failed ({status})");
    }

    response.json::<UsageSnapshot>().await.context("failed to parse usage response")
}

#[cfg(test)]
mod tests {
    use rstest::rstest;

    use super::*;

    #[test]
    fn deserializes_server_payload() {
        // Shape documented in the hub's CliUsageController / credits_payload.
        let json = r#"{
            "period": "calendar_monthly",
            "resets_at": "2026-08-01T00:00:00Z",
            "requests": {"used": 3, "limit": -1},

View on GitHub (pinned to c0c717ab04)

Solutions

1. Check the status in the message; re-authenticate on 401/403
2. Refresh the hub session / re-login
3. Verify the AI gateway configuration and network connectivity
4. Retry later on 5xx/429 responses

// validate session exists before fetching usage
let token = session.token().ok_or_else(|| eyre!("no active session"))?;

match fetch_usage().await {
    Ok(u) => u,
    Err(e) if e.to_string().contains("401") => {
        refresh_session().await?;
        fetch_usage().await?
    }
    Err(e) if e.to_string().contains("429") || e.to_string().contains("5") => {
        tokio::time::sleep(BACKOFF).await;
        fetch_usage().await?
    }
    Err(e) => return Err(e),
}

When it happens

Trigger: The usage endpoint returns non-success status: invalid/expired token (401), forbidden account (403), unknown account, gateway 5xx, or rate limit (429)

Common situations: Checking usage with a stale session after the token expired, during gateway incidents, or when the account has been suspended

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• model list request failed ({status})
• Hub account deletion failed with status {status}
• username already in use
• failed to parse server version: {:?}
• Server not reporting its version: it is either too old or un

AI-assisted analysis of atuinsh/atuin@c0c717ab04 (2026-09-12). Data as JSON: /api/errors/7ba02491697e31c2. Report an issue: GitHub.