HTTP Request Headers: What They Are and Why They Matter

Every HTTP request is made up of three parts: the start line, headers, and a body. Headers are the request’s metadata: who is sending it, what format is expected in return, and how the sender is authenticated.

What Headers Are

A header is a Name: Value pair. They are sent before the request body and describe the context.

GET /user HTTP/1.1
Host: api.github.com
Authorization: Bearer replace-with-your-token
Accept: application/vnd.github+json
User-Agent: my-python-app/1.0

Headers in requests

import os
import requests

headers = {
    "Authorization": f"Bearer {os.environ['GITHUB_TOKEN']}",
    "Accept": "application/vnd.github+json",
    "X-GitHub-Api-Version": "2022-11-28",
}

response = requests.get("https://api.github.com/user", headers=headers, timeout=10)
response.raise_for_status()

The headers= parameter accepts a plain Python dictionary.

The Most Important Headers

Authorization — authentication

Sends credentials to access the API.

# Bearer token (GitHub and most modern APIs):
"Authorization": "Bearer ghp_your_token_here"

# API Key (some APIs):
"Authorization": "Api-Key your_api_key"

# Basic Auth (legacy):
"Authorization": "Basic base64(login:password)"

Without this header, protected endpoints return 401 Unauthorized.

Accept — expected response format

# JSON (the standard for most APIs):
"Accept": "application/json"

# GitHub-specific format:
"Accept": "application/vnd.github+json"

# File download:
"Accept": "application/octet-stream"

If omitted, the server picks the format on its own (usually JSON).

Content-Type — request body format

Used in POST/PUT/PATCH to tell the server how to parse the body.

"Content-Type": "application/json"

requests sets this header automatically when you use json=:

# Content-Type is set automatically:
requests.post(url, json={"name": "repo"}, headers=headers)

# If you pass raw data manually, set it explicitly:
import json
requests.post(url, data=json.dumps({"name": "repo"}),
              headers={**headers, "Content-Type": "application/json"})

User-Agent — client identifier

Tells the server what kind of program is making the request. Some APIs require it explicitly.

"User-Agent": "my-github-tool/1.0"

The GitHub API requires a non-empty User-Agent — without it you’ll get a 403.

X-GitHub-Api-Version — API version

"X-GitHub-Api-Version": "2022-11-28"

Some APIs support multiple versions. Pinning the version protects you from unexpected breaking changes.

Reading Response Headers

response = requests.get(url, headers=headers)

# Server response headers:
print(response.headers)
print(response.headers["Content-Type"])
print(response.headers.get("X-RateLimit-Remaining"))  # remaining quota

GitHub includes rate-limit headers in responses:
- X-RateLimit-Limit — maximum requests per hour
- X-RateLimit-Remaining — how many are left
- X-RateLimit-Reset — when the limit resets (Unix timestamp)

Common Errors

401 Unauthorized

The Authorization header is missing or the token is invalid.

403 Forbidden

The token is valid but doesn’t have permission for this action. For example, a read-only token trying to create a repository.

415 Unsupported Media Type

Wrong Content-Type. The server doesn’t know how to parse the format you sent.

Summary

Headers are the request’s metadata. The three most important:
- Authorization — who you are
- Accept — what format you expect back
- Content-Type — what format you’re sending (in POST/PATCH)