cowboy_req:parse_header - Parse the given HTTP header


parse_header(Name, Req)          -> ParsedValue | Default
parse_header(Name, Req, Default) -> ParsedValue | Default

Name        :: binary()
Req         :: cowboy_req:req()
ParsedValue :: any()
Default     :: any()

Parse the given HTTP header.

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

The type of the parsed value varies depending on the header. Similarly, the default value when calling cowboy_req:parse_header/2 differs depending on the header.



Desired HTTP header name as a lowercase binary string.


The Req object.


Default value returned when the header is missing.

Return value

The parsed header value varies depending on the header. When the header is missing, the default argument is returned.


The following snippets detail the types returned by the different headers. Unless mentioned otherwise, the default value when the header is missing will be undefined:

parse_header(<<"accept">>, Req)
    -> [{{Type, SubType, Params}, Quality, AcceptExt}]

Type      :: binary()               %% case insensitive
SubType   :: binary()               %% case insensitive
Params    :: [{Key, Value}]
Quality   :: 0..1000
AcceptExt :: [Key | {Key, Value}]
Key       :: binary()               %% case insensitive
Value     :: binary()               %% case sensitive
accept-charset, accept-encoding and accept-language
parse_header(Name, Req) -> [{Value, Quality}]

Name    :: <<"accept-charset">>
         | <<"accept-encoding">>
         | <<"accept-language">>
Value   :: binary()                 %% case insensitive
Quality :: 0..1000
parse_header(<<"authorization">>, Req)
    -> {basic, Username :: binary(), Password :: binary()}
     | {bearer, Token :: binary()}
     | {digest, [{Key :: binary(), Value :: binary()}]}
parse_header(<<"content-length">>, Req) -> non_neg_integer()

When the content-length header is missing, 0 is returned.

parse_header(<<"content-type">>, Req)
    -> {Type, SubType, Params}

Type      :: binary()               %% case insensitive
SubType   :: binary()               %% case insensitive
Params    :: [{Key, Value}]
Key       :: binary()               %% case insensitive
Value     :: binary()               %% case sensitive;

Note that the value for the charset parameter is case insensitive and returned as a lowercase binary string.

parse_header(<<"cookie">>, Req) -> [{Name, Value}]

Name  :: binary()                   %% case sensitive
Value :: binary()                   %% case sensitive

When the cookie header is missing, [] is returned.

While an empty cookie header is not valid, some clients do send it. Cowboy will in this case also return [].

parse_header(<<"expect">>, Req) -> continue
if-match and if-none-match
parse_header(Name, Req)
    -> '*' | [{weak | strong, OpaqueTag}]

Name      :: <<"if-match">>
           | <<"if-none-match">>
OpaqueTag :: binary()               %% case sensitive
if-modified-since and if-unmodified-since
parse_header(Name, Req) -> calendar:datetime()
parse_header(<<"range">>, Req) -> {From, To} | Final

From  :: non_neg_integer()
To    :: non_neg_integer() | infinity
Final :: neg_integer()
parse_header(<<"sec-websocket-extensions">>, Req)
    -> [{Extension, Params}]

Extension :: binary()               %% case sensitive
Params    :: [Key | {Key, Value}]
Key       :: binary()               %% case sensitive
Value     :: binary()               %% case sensitive
sec-websocket-protocol and upgrade
parse_header(Name, Req) -> [Token]

Name  :: <<"sec-websocket-protocol">>
       | <<"upgrade">>
Token :: binary()                   %% case insensitive
parse_header(<<"x-forwarded-for">>, Req) -> [Token]

Token :: binary()                   %% case sensitive
Unknown headers
parse_header(_, Req) -> {undefined, RawValue}


  • 2.0: Only the parsed header value is returned, it is no longer wrapped in a tuple.
  • 1.0: Function introduced.


Parse the accept header with a custom default value
%% Accept everything when header is missing.
Accept = cowboy_req:parse_header(<<"accept">>, Req,
    [{{ <<"*">>, <<"*">>, []}, 1000, []}]).
Parse the content-length header
%% Default content-length is 0.
Length = cowboy_req:header(<<"content-length">>, Req).

See also

cowboy_req(3), cowboy_req:header(3), cowboy_req:headers(3)

Cowboy 2.7 Function Reference


Version select

Like my work? Donate!

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and is fantastic:

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.