How to read a response header

Short answer: response.headers().get("header-name") hands back Option<&HeaderValue>. Header names are case-insensitive — reqwest stores them lowercased, so any spelling hits the same entry — and the value becomes text with .to_str(). When an API meters you, read x-ratelimit-remaining and x-ratelimit-reset and wait for the window rather than hammering the endpoint.

The dependencies

This picks up the fetch project from How to set a timeout on a request. The same two crates, no features beyond reqwest’s defaults:

[dependencies]
reqwest = "0.13.5"
tokio = { version = "1.53.3", features = ["macros", "rt-multi-thread"] }

Reading one header

Response::headers() gives you a &HeaderMap. A lookup is two small failures deep: get returns None when the server didn’t send the header, and a header value is bytes, so to_str() returns a Result that fails on values which aren’t plain ASCII. Both are worth handling where they happen:

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let response = reqwest::get("https://httpbin.org/json").await?;
    let headers = response.headers();

    for name in ["content-type", "x-ratelimit-remaining"] {
        match headers.get(name) {
            Some(value) => println!("{name}: {}", value.to_str().unwrap_or("<not text>")),
            None => println!("{name}: missing"),
        }
    }
    Ok(())
}

Run this in the Rust Playground

cargo run prints (cargo’s own Compiling and Finished lines are not shown):

content-type: application/json
x-ratelimit-remaining: missing

The two crates re-export the map and its pieces — reqwest::header::{HeaderMap, HeaderName, HeaderValue} — so nothing from the http crate needs to be a direct dependency. to_str()’s error type is header::ToStrError, and it isn’t one of the errors reqwest::Error converts from, which is why the code above handles it locally instead of reaching for ?. A value that isn’t ASCII text still reads fine as bytes through as_bytes().

Names don’t care about case

HTTP field names are case-insensitive on the wire: Content-Type, content-type and CONTENT-TYPE are the same field, and a server is free to send any of them. reqwest leans on that rather than fighting it. HeaderName lowercases on the way into the map, get lowercases whatever you pass it, and the map always reports names in their lowercased form:

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let url = "https://httpbin.org/response-headers?X-RateLimit-Remaining=42&X-RateLimit-Reset=1730000000";
    let response = reqwest::get(url).await?;
    let headers = response.headers();

    for name in [
        "X-RateLimit-Remaining",
        "x-ratelimit-remaining",
        "X-RATELIMIT-REMAINING",
    ] {
        println!("{name} -> {:?}", headers.get(name).map(|value| value.to_str()));
    }

    let mut names: Vec<&str> = headers
        .keys()
        .map(|name| name.as_str())
        .filter(|name| name.starts_with("x-ratelimit"))
        .collect();
    names.sort();
    for name in names {
        println!("{name}");
    }
    Ok(())
}

Run this in the Rust Playground

X-RateLimit-Remaining -> Some(Ok("42"))
x-ratelimit-remaining -> Some(Ok("42"))
X-RATELIMIT-REMAINING -> Some(Ok("42"))
x-ratelimit-remaining
x-ratelimit-reset

Three spellings, one entry. That’s also why there’s no case-sensitive get and no way to store a header under a mixed-case name: by the time a name is in the map, its case is gone. The practical consequence is that your own code should stop writing the case the server happened to use — match on the lowercased form and it works against every server.

The rate limit you should respect

An API that meters you says so in its response headers. x-ratelimit-remaining counts the requests left in the current window and x-ratelimit-reset says when the window reopens, as epoch seconds. Reading them beats guessing a sleep, and it’s the difference between one well-timed wait and a retry loop that keeps you locked out. httpbin’s /response-headers endpoint echoes whatever headers you ask for, which makes the mechanics testable without an account:

use std::time::{Duration, SystemTime, UNIX_EPOCH};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let reset = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .unwrap()
        .as_secs()
        + 2;
    let url = format!(
        "https://httpbin.org/response-headers?X-RateLimit-Remaining=0&X-RateLimit-Reset={reset}"
    );

    let response = reqwest::get(&url).await?;
    let headers = response.headers();
    let remaining = headers
        .get("x-ratelimit-remaining")
        .and_then(|value| value.to_str().ok());
    let reset_at = headers
        .get("x-ratelimit-reset")
        .and_then(|value| value.to_str().ok())
        .and_then(|value| value.parse::<u64>().ok());

    if remaining == Some("0") {
        let now = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .unwrap()
            .as_secs();
        let wait = reset_at.map_or(0, |reset| reset.saturating_sub(now));
        println!("out of requests; waiting for the window to reset");
        tokio::time::sleep(Duration::from_secs(wait)).await;
        println!("window reset");
    }
    Ok(())
}

Run this in the Rust Playground

out of requests; waiting for the window to reset
window reset

The reset value is a timestamp in seconds, so it only has one-second resolution — a wait computed from it can come out a second early, and a request that early can still be refused. The fix isn’t a cleverer formula: it’s checking the header again on the next response, which is what a loop around this does.

Two neighbouring conventions are worth knowing. Retry-After is the same idea sent from the other side, attached to a 429 or 503 response; it’s either a number of seconds or an HTTP date, and the date form needs a date parser. And header names aren’t standardised across APIs — GitHub spells them x-ratelimit-remaining, other services pick their own — so read each API’s docs rather than assuming a name.

How to set a timeout on a request — a deadline on the same client, for a response that never comes.
How to make a GET request — where the response and its headers come from.
How to deserialize JSON into a struct — what to do with the body once it arrives.

How to read a response header

The dependencies

Reading one header

Names don’t care about case

The rate limit you should respect

Next