Заголовки HTTP-запроса: что такое headers и зачем они нужны

Каждый HTTP-запрос состоит из трёх частей: стартовой строки, заголовков и тела. Заголовки — это метаданные запроса: кто отправляет, что ожидает получить, как авторизован.

Что такое заголовки

Заголовок — это пара Имя: Значение. Они передаются перед телом запроса и описывают контекст.

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

Заголовки в requests

import requests

headers = {
    "Authorization": "Bearer ghp_abc123def456",
    "Accept": "application/vnd.github+json",
    "X-GitHub-Api-Version": "2022-11-28",
}

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

Параметр headers= принимает обычный Python-словарь.

Самые важные заголовки

Authorization — авторизация

Передаёт учётные данные для доступа к API.

# Bearer token (GitHub, большинство современных API):
"Authorization": "Bearer ghp_your_token_here"

# API Key (некоторые API):
"Authorization": "Api-Key your_api_key"

# Basic Auth (устаревший вариант):
"Authorization": "Basic base64(login:password)"

Без этого заголовка защищённые эндпоинты вернут 401 Unauthorized.

Accept — какой формат ответа ожидаем

# JSON (стандарт для большинства API):
"Accept": "application/json"

# Специфичный формат GitHub:
"Accept": "application/vnd.github+json"

# Скачивание файла:
"Accept": "application/octet-stream"

Если не указывать — сервер выберет формат сам (обычно JSON).

Content-Type — формат тела запроса

Используется в POST/PUT/PATCH чтобы сказать серверу как читать тело.

"Content-Type": "application/json"

requests добавляет этот заголовок автоматически когда используешь json=:

# Content-Type устанавливается автоматически:
requests.post(url, json={"name": "repo"}, headers=headers)

# Если передать данные вручную — нужно указать явно:
import json
requests.post(url, data=json.dumps({"name": "repo"}),
              headers={**headers, "Content-Type": "application/json"})

User-Agent — идентификатор клиента

Говорит серверу что за программа делает запрос. Некоторые API требуют его явно.

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

GitHub API требует непустой User-Agent — без него вернёт 403.

X-GitHub-Api-Version — версия API

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

Некоторые API поддерживают несколько версий. Явное указание версии защищает от неожиданных изменений.

Просмотр заголовков ответа

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

# Заголовки ответа сервера:
print(response.headers)
print(response.headers["Content-Type"])
print(response.headers.get("X-RateLimit-Remaining"))  # остаток лимита

GitHub возвращает заголовки с лимитами:
- X-RateLimit-Limit — максимум запросов в час
- X-RateLimit-Remaining — сколько осталось
- X-RateLimit-Reset — когда сбросится лимит (Unix timestamp)

Частые ошибки

401 Unauthorized

Заголовок Authorization отсутствует или токен неверный.

403 Forbidden

Токен есть, но нет прав на это действие. Например токен только для чтения а ты пытаешься создать репозиторий.

415 Unsupported Media Type

Неверный Content-Type. Сервер не умеет читать формат который ты отправил.

Итог

Заголовки — это метаданные запроса. Три самых важных:
- Authorization — кто ты
- Accept — что ожидаешь получить
- Content-Type — что отправляешь (в POST/PATCH)