Response Headers

Generated clients retain response headers for both successful and non-successful HTTP responses. Header preservation is not limited to headers declared in the OpenAPI document: an undeclared Retry-After, request ID, tracing header, cookie, or vendor header remains available through the HTTP backend’s native header collection.

OpenAPI-declared response headers additionally receive generated convenience accessors. Simple string, integer, number, and boolean schemas map to the corresponding language type. Accessors are always optional because a server can omit a declared header or send a value that does not match its schema. A missing or malformed value does not turn an otherwise valid response into an error. Scalar parsing uses the same wire policy across generators: booleans are the lowercase literals true and false, integers are signed decimal digits, and numbers are finite decimal values with an optional exponent. Other spellings return the accessor’s empty result while remaining available in the native header collection.

Retry-After should normally be declared as a string because HTTP allows either delay seconds or an HTTP date:

components:
  headers:
    RetryAfter:
      description: Delay in seconds or an HTTP date before retrying.
      schema:
        type: string

paths:
  /jobs:
    post:
      responses:
        "429":
          description: Too many requests.
          headers:
            Retry-After:
              $ref: "#/components/headers/RetryAfter"

Reading headers

Generated accessor names follow the operation and header names in the OpenAPI document. This Rust example uses an accessor for each declared header and falls back to the backend-native header map for an undeclared tracing header:

#![allow(unused)]
fn main() {
match api.create_resource(&request).await {
    Ok(response) => {
        let request_id = response.x_request_id_header();
        let traceparent = response
            .headers
            .get("traceparent")
            .and_then(|value| value.to_str().ok());

        println!("request_id={request_id:?} traceparent={traceparent:?}");
    }
    Err(error) => {
        let retry_after = error.retry_after_header().map(str::to_owned);

        // Erase the payload type when only common response metadata is needed.
        let error: ApiCallError = error.into();
        let traceparent = error
            .headers()
            .and_then(|headers| headers.get("traceparent"))
            .and_then(|value| value.to_str().ok());

        eprintln!("retry_after={retry_after:?} traceparent={traceparent:?}");
    }
}
}

In this example, X-Request-Id and Retry-After are declared in OpenAPI, so the generator provides typed accessors. traceparent is undeclared and remains available through the native header map. Match the operation-specific error before converting it to ApiCallError when its decoded body is needed; see Generated Error Handling.

Generated access

The native collection remains the authority when a caller needs undeclared headers or backend-specific parsing. A generated scalar accessor reads one value only. Duplicate-field behavior follows the HTTP backend; some backends retain each field while others coalesce duplicate fields into one value.

Browser visibility

TypeScript Fetch follows the browser Fetch API. For cross-origin requests, JavaScript can only read CORS-safelisted response headers plus headers named by the server’s Access-Control-Expose-Headers response header. The browser may therefore hide Retry-After even though the generated client does not drop it.