HTTP статус коды: полная таблица с описанием (1xx–5xx)

Введение

Каждый раз, когда ваш браузер или приложение отправляет запрос к серверу, в ответ приходит трёхзначный числовой код — HTTP статус код. Этот код сообщает, что произошло: запрос выполнен успешно, ресурс переехал, клиент ошибся или сервер сломался.

Знание HTTP кодов — обязательный навык для любого разработчика, работающего с API, веб-приложениями или микросервисами. Без понимания этих кодов вы не сможете корректно обрабатывать ошибки, отлаживать запросы и строить надёжные системы.

В этой статье вы найдёте:

• ✅ Полную таблицу всех основных HTTP статус кодов
• ✅ Описание каждого кода на русском языке
• ✅ Примеры кода для обработки на JavaScript, Python и PHP
• ✅ Типичные ошибки при работе с API
• ✅ FAQ по самым частым вопросам

Что такое HTTP статус коды

HTTP статус код (HTTP Status Code) — это трёхзначное число, которое сервер возвращает клиенту в ответ на HTTP-запрос. Код сообщает о результате обработки запроса: был ли он успешен, требуется ли перенаправление, допустил ли клиент ошибку или произошёл сбой на сервере.

Каждый HTTP-ответ содержит статус код в первой строке:

HTTP/1.1 200 OK
Content-Type: application/json

{"message": "Успех!"}

Здесь 200 — это статус код, а OK — текстовое описание (reason phrase).

Структура кодов (5 классов)

Все HTTP статус коды делятся на 5 классов по первой цифре. Зная только первую цифру, вы уже понимаете общий смысл ответа:

1xx — Информационные коды

Информационные коды сообщают, что сервер принял запрос и продолжает обработку. В повседневной разработке они встречаются редко, но знать их полезно.

2xx — Успех

Коды класса 2xx означают, что запрос клиента был принят и успешно обработан. Это самые желанные коды в ответе API.

Примеры использования 200 и 201

// 200 OK — получение данных
fetch('/api/users')
  .then(res => {
    if (res.status === 200) {
      return res.json();
    }
  });

// 201 Created — создание нового ресурса
fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Иван' })
}).then(res => {
  if (res.status === 201) {
    console.log('Пользователь создан');
    // Заголовок Location содержит URL нового ресурса
    console.log(res.headers.get('Location'));
  }
});

3xx — Перенаправление

Коды класса 3xx сообщают, что для завершения запроса клиенту нужно выполнить дополнительное действие — обычно перейти по другому URL.

4xx — Ошибки клиента

Коды класса 4xx означают, что ошибка на стороне клиента. Сервер не может обработать запрос из-за некорректных данных, отсутствия авторизации или обращения к несуществующему ресурсу. Это самый важный класс для API-разработки.

400 Bad Request

Сервер не может обработать запрос из-за некорректного синтаксиса или невалидных данных.

Когда возникает:

• Невалидный JSON в теле запроса
• Отсутствуют обязательные поля
• Неправильный формат данных (email, дата)

// Пример: отправляем невалидный JSON
fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: '{ invalid json }'
});
// Ответ: 400 Bad Request
// { "error": "Invalid JSON in request body" }

401 Unauthorized

Клиент не авторизован. Требуется предоставить учётные данные (токен, логин/пароль).

Когда возникает:

• Отсутствует заголовок Authorization
• Токен истёк или недействителен
• Неправильные логин/пароль

// Запрос без токена авторизации
fetch('/api/profile');
// Ответ: 401 Unauthorized
// { "error": "Token is missing or expired" }

// Правильный запрос с токеном
fetch('/api/profile', {
  headers: { 'Authorization': 'Bearer eyJhbGciOi...' }
});
// Ответ: 200 OK

403 Forbidden

Сервер понял запрос, но отказывает в доступе. Авторизация пройдена, но прав недостаточно.

Когда возникает:

• Пользователь пытается получить данные другого пользователя
• Роль не имеет доступа к ресурсу (например, обычный пользователь запрашивает админ-панель)
• IP-адрес заблокирован

404 Not Found

Запрашиваемый ресурс не найден на сервере.

Когда возникает:

• Неправильный URL
• Ресурс был удалён
• Опечатка в endpoint

// Запрос к несуществующему ресурсу
fetch('/api/users/99999');
// Ответ: 404 Not Found
// { "error": "User with ID 99999 not found" }

405 Method Not Allowed

HTTP-метод не поддерживается для данного ресурса.

Когда возникает:

• Отправлен POST на endpoint, который принимает только GET
• Попытка DELETE на ресурс, который нельзя удалять

// Endpoint принимает только GET
fetch('/api/reports', { method: 'DELETE' });
// Ответ: 405 Method Not Allowed
// Заголовок Allow: GET, POST

408 Request Timeout

Сервер устал ждать запрос от клиента. Клиент слишком долго отправлял данные.

409 Conflict

Запрос конфликтует с текущим состоянием сервера.

Когда возникает:

• Попытка создать пользователя с email, который уже занят
• Конфликт версий при одновременном редактировании

// Попытка зарегистрировать существующий email
fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'ivan@example.com' })
});
// Ответ: 409 Conflict
// { "error": "User with this email already exists" }

413 Payload Too Large

Тело запроса слишком большое. Сервер отказывается его обрабатывать.

Когда возникает:

• Загрузка файла, превышающего лимит
• Слишком большой JSON в теле запроса

415 Unsupported Media Type

Сервер не поддерживает формат данных в запросе.

Когда возникает:

• Отправлен XML, а сервер принимает только JSON
• Отсутствует заголовок Content-Type

422 Unprocessable Entity

Сервер понял запрос, синтаксис корректен, но не может обработать содержащиеся в нём данные.

Когда возникает:

• Валидация данных не пройдена (email невалидный, возраст отрицательный)
• Бизнес-логика не позволяет выполнить действие

// Отправляем невалидные данные
fetch('/api/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'not-an-email', age: -5 })
});
// Ответ: 422 Unprocessable Entity
// {
//   "errors": {
//     "email": "Некорректный формат email",
//     "age": "Возраст должен быть положительным числом"
//   }
// }

429 Too Many Requests

Клиент отправил слишком много запросов за единицу времени (rate limiting).

Когда возникает:

• Превышен лимит запросов к API
• Слишком частые попытки авторизации

// Ответ при превышении лимита
// HTTP/1.1 429 Too Many Requests
// Retry-After: 60
// X-RateLimit-Limit: 100
// X-RateLimit-Remaining: 0
// X-RateLimit-Reset: 1708700000

// Обработка 429 с повторной попыткой
async function fetchWithRetry(url, retries = 3) {
  const response = await fetch(url);

  if (response.status === 429 && retries > 0) {
    const retryAfter = response.headers.get('Retry-After') || 5;
    console.log(`Rate limit. Повтор через ${retryAfter}с...`);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return fetchWithRetry(url, retries - 1);
  }

  return response;
}

5xx — Ошибки сервера

Коды класса 5xx означают, что проблема на стороне сервера. Запрос клиента был корректным, но сервер не смог его обработать. Обычно это повод для алерта в мониторинге.

500 Internal Server Error

Универсальная ошибка сервера. Что-то пошло не так, и сервер не может точнее описать проблему.

Причины:

• Необработанное исключение в коде
• Ошибка подключения к базе данных
• Баг в серверной логике
• Не хватает памяти или дискового пространства

// Серверный код (Node.js) — необработанное исключение
app.get('/api/data', async (req, res) => {
  // Если DB недоступна, выбросится исключение
  const data = await db.query('SELECT * FROM users');
  // Без try/catch клиент получит 500
  res.json(data);
});

// Правильная обработка
app.get('/api/data', async (req, res) => {
  try {
    const data = await db.query('SELECT * FROM users');
    res.json(data);
  } catch (error) {
    console.error('DB Error:', error);
    res.status(500).json({ error: 'Внутренняя ошибка сервера' });
  }
});

501 Not Implemented

Сервер не поддерживает запрошенную функциональность. Endpoint существует, но метод ещё не реализован.

Пример: API в разработке, где некоторые endpoints заглушены.

502 Bad Gateway

Промежуточный сервер (nginx, load balancer, CDN) получил некорректный ответ от upstream-сервера.

Причины:

• Backend-приложение упало или не запущено
• Backend вернул невалидный ответ
• Проблемы с сетью между nginx и backend

503 Service Unavailable

Сервер временно недоступен. Обычно из-за перегрузки или планового обслуживания.

Причины:

• Сервер перегружен запросами
• Плановое обновление (deploy)
• Зависимый сервис недоступен

// Заголовок Retry-After указывает, когда повторить
// HTTP/1.1 503 Service Unavailable
// Retry-After: 120
// { "error": "Сервис временно недоступен. Повторите через 2 минуты." }

504 Gateway Timeout

Промежуточный сервер не дождался ответа от upstream-сервера.

Причины:

• Backend обрабатывает запрос слишком долго
• Тяжёлый SQL-запрос к базе данных
• Зависание внешнего API, от которого зависит backend

Как обрабатывать статус коды в коде

Рассмотрим примеры правильной обработки HTTP кодов на трёх языках.

JavaScript (fetch)

async function apiRequest(url, options = {}) {
  const response = await fetch(url, options);

  switch (response.status) {
    case 200:
    case 201:
      return await response.json();
    case 204:
      return null;
    case 400:
      throw new Error('Некорректный запрос');
    case 401:
      throw new Error('Необходима авторизация');
    case 403:
      throw new Error('Доступ запрещён');
    case 404:
      throw new Error('Ресурс не найден');
    case 422: {
      const body = await response.json();
      throw new Error(`Ошибка валидации: ${JSON.stringify(body.errors)}`);
    }
    case 429:
      throw new Error('Слишком много запросов');
    case 500:
      throw new Error('Ошибка сервера');
    case 502:
      throw new Error('Сервер недоступен (Bad Gateway)');
    case 503:
      throw new Error('Сервис временно недоступен');
    case 504:
      throw new Error('Таймаут сервера');
    default:
      throw new Error(`Неизвестная ошибка: ${response.status}`);
  }
}

// Использование
try {
  const users = await apiRequest('/api/users');
  console.log(users);
} catch (error) {
  console.error(error.message);
}

Python (requests)

import requests

def api_request(url, method='GET', **kwargs):
    response = requests.request(method, url, **kwargs)

    if response.status_code == 200:
        return response.json()
    elif response.status_code == 201:
        return response.json()
    elif response.status_code == 204:
        return None
    elif response.status_code == 400:
        raise Exception('Некорректный запрос')
    elif response.status_code == 401:
        raise Exception('Необходима авторизация')
    elif response.status_code == 403:
        raise Exception('Доступ запрещён')
    elif response.status_code == 404:
        raise Exception('Ресурс не найден')
    elif response.status_code == 422:
        errors = response.json().get('errors', {})
        raise Exception(f'Ошибка валидации: {errors}')
    elif response.status_code == 429:
        retry_after = response.headers.get('Retry-After', 5)
        raise Exception(f'Rate limit. Повторите через {retry_after}с')
    elif response.status_code >= 500:
        raise Exception(f'Ошибка сервера: {response.status_code}')
    else:
        raise Exception(f'Неизвестная ошибка: {response.status_code}')

# Использование
try:
    users = api_request('https://api.example.com/users')
    print(users)
except Exception as e:
    print(f'Ошибка: {e}')

PHP (cURL)

<?php

function apiRequest(string $url, string $method = 'GET', ?array $data = null): mixed
{
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);

    if ($data !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json'
        ]);
    }

    $response = curl_exec($ch);
    $statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    return match (true) {
        $statusCode === 200, $statusCode === 201 => json_decode($response, true),
        $statusCode === 204 => null,
        $statusCode === 400 => throw new Exception('Некорректный запрос'),
        $statusCode === 401 => throw new Exception('Необходима авторизация'),
        $statusCode === 403 => throw new Exception('Доступ запрещён'),
        $statusCode === 404 => throw new Exception('Ресурс не найден'),
        $statusCode === 429 => throw new Exception('Слишком много запросов'),
        $statusCode >= 500   => throw new Exception("Ошибка сервера: {$statusCode}"),
        default               => throw new Exception("Неизвестная ошибка: {$statusCode}"),
    };
}

// Использование
try {
    $users = apiRequest('https://api.example.com/users');
    print_r($users);
} catch (Exception $e) {
    echo "Ошибка: " . $e->getMessage();
}

Самые частые ошибки при работе с API

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Ошибка валидации данных",
    "details": {
      "email": "Некорректный формат email",
      "age": "Должно быть положительным числом"
    }
  }
}

FAQ

401 → «Кто ты? Покажи пропуск»  (нет токена / токен невалидный)
403 → «Я тебя знаю, но сюда нельзя» (нет прав на ресурс)

502 → Backend ответил чушь (crash, невалидный ответ)
504 → Backend молчит (зависание, долгий запрос к БД)

Заключение

HTTP статус коды — фундамент общения между клиентом и сервером. Правильное использование кодов делает ваш API понятным, предсказуемым и удобным для разработчиков. Неправильное — приводит к часам отладки и бесконечным вопросам от клиентов «а почему не работает?».

Статья опубликована: 23 февраля 2026
Автор: LightBox API Team