Пошук уроків, статей та іншого контенту
Навчимося читати та вибирати HTTP-коди успішних відповідей, помилок клієнта й помилок сервера.
Коли клієнт надсилає HTTP-запит до сервера, сервер повертає відповідь. Вона містить:
код статусу;
заголовки;
тіло відповіді, якщо воно потрібне.
Код статусу — це число з трьох цифр, яке коротко описує результат обробки запиту.
Наприклад:
HTTP/1.1 200 OKУ цьому прикладі:
200 — код статусу;
OK
Клієнт може використовувати код статусу, щоб зрозуміти, чи виконано запит успішно, чи потрібно виправити дані, чи проблема виникла на сервері.
Перша цифра коду визначає його групу:
| Група | Значення | |---|---| | 1xx | інформаційні відповіді | | 2xx | успішне виконання запиту | | 3xx | перенаправлення | | 4xx | помилка з боку клієнта | | 5xx | помилка з боку сервера |
У цій темі зосередимося на кодах 2xx, 4xx і 5xx.
Коди 2xx означають, що сервер успішно обробив запит.
200 OKНайпоширеніший код успішної відповіді.
Використовуйте його, коли:
дані успішно отримано;
ресурс успішно оновлено;
операція виконана й має результат у тілі відповіді.
Наприклад, сервер повертає список користувачів:
HTTP/1.1 200 OK
Content-Type: application/json
[{"id":1,"name":"Олена"}]201 CreatedОзначає, що сервер успішно створив новий ресурс.
Зазвичай цей код використовують після POST-запиту, який створює користувача, товар або інший ресурс.
HTTP/1.1 201 Created
Content-Type: application/json
{"id":2,"name":"Андрій"}204 No ContentОзначає, що операція успішна, але сервер не повертає тіло відповіді.
Цей код зручно використовувати, коли ресурс успішно видалено:
HTTP/1.1 204 No ContentВідповідь із кодом 204 не повинна містити тіла.
Коди 4xx означають, що проблема пов’язана із запитом клієнта. Наприклад, клієнт надіслав неправильні дані або звернувся до ресурсу, якого не існує.
400 Bad RequestЗапит має неправильний формат або містить некоректні дані.
Приклади:
відсутнє обов’язкове поле;
JSON має неправильний синтаксис;
значення поля має неприпустимий формат.
{
"error": "Поле email є обов’язковим"
}Код відповіді:
HTTP/1.1 400 Bad Request400 означає: сервер не може коректно обробити цей запит у поточному вигляді.
401 UnauthorizedОзначає, що клієнт не пройшов автентифікацію.
Наприклад, запит не містить токена доступу або токен недійсний.
Назва Unauthorized може бути дещо заплутаною: на практиці цей код найчастіше означає саме відсутність коректної автентифікації.
403 ForbiddenОзначає, що сервер зрозумів запит, але забороняє виконувати цю дію.
Наприклад:
користувач увійшов у систему;
але не має прав адміністратора;
тому не може видалити ресурс.
Різниця між 401 і 403:
401 — клієнт не підтвердив свою особу;
403 — особу підтверджено, але доступ заборонено.
404 Not FoundОзначає, що запитаний ресурс не знайдено.
Приклади:
URL не відповідає жодному маршруту;
користувач із вказаним ідентифікатором не існує;
файл або інший ресурс відсутній.
HTTP/1.1 404 Not Found
Content-Type: application/json
{"error":"Користувача не знайдено"}409 ConflictОзначає конфлікт із поточним станом ресурсу.
Наприклад, користувач намагається зареєструвати email, який уже використовується:
HTTP/1.1 409 Conflict
Content-Type: application/json
{"error":"Користувач із таким email уже існує"}422 Unprocessable EntityОзначає, що формат запиту зрозумілий, але значення не проходять перевірку.
Наприклад, JSON правильний, але пароль занадто короткий або дата має недопустиме значення.
У різних API для помилок перевірки можуть використовувати 400 або 422. Важливо дотримуватися одного підходу в межах конкретного API.
Коди 5xx означають, що запит був коректним або принаймні зрозумілим, але сервер не зміг його обробити.
500 Internal Server ErrorЗагальна помилка сервера.
Вона може виникнути через:
необроблений виняток у коді;
помилку підключення до внутрішнього сервісу;
несподівану помилку під час обробки запиту.
500 не варто використовувати для помилок введення даних. Якщо клієнт надіслав неправильний email, це помилка 4xx, а не 500.
502 Bad GatewayСервер, який обробляє запит як посередник, отримав неправильну відповідь від іншого сервера.
Наприклад, API звертається до сервісу платежів, але той повернув некоректну відповідь.
503 Service UnavailableСервіс тимчасово недоступний.
Причини можуть бути такими:
сервер перевантажений;
тривають технічні роботи;
залежний сервіс тимчасово не працює.
У Node.js із вбудованим модулем http код статусу можна встановити через властивість response.statusCode:
response.statusCode = 200;Після цього можна надіслати відповідь:
response.end('Успішно');Також код і заголовки можна встановити за допомогою response.writeHead():
response.writeHead(201, {
'Content-Type': 'application/json; charset=utf-8'
});
response.end(JSON.stringify({ id: 1 }));Цей сервер демонструє кілька типових кодів статусу:
const http = require('node:http');
const server = http.createServer((request, response) => {
response.setHeader('Content-Type', 'application/json; charset=utf-8');
if (request.method === 'GET' && request.url === '/users') {
response.statusCode = 200;
response.end(JSON.stringify([
{ id: 1, name: 'Олена' },
{ id: 2, name: 'Андрій' }
]));
return;
}
if (request.method === 'POST' && request.url === '/users') {
response.statusCode = 201;
response.end(JSON.stringify({
id: 3,
name: 'Марія'
}));
return;
}
if (request.method === 'DELETE' && request.url === '/users/3') {
response.statusCode = 204;
response.removeHeader('Content-Type');
response.end();
return;
}
if (request.method === 'GET' && request.url === '/bad-request') {
response.statusCode = 400;
response.end(JSON.stringify({
error: 'Запит містить некоректні дані'
}));
return;
}
if (request.method === 'GET' && request.url === '/error') {
response.statusCode = 500;
response.end(JSON.stringify({
error: 'Внутрішня помилка сервера'
}));
return;
}
response.statusCode = 404;
response.end(JSON.stringify({
error: 'Маршрут не знайдено'
}));
});
server.listen(3000, () => {
console.log('Сервер запущено на http://localhost:3000');
});Збережіть код у файлі server.js і запустіть:
node server.jsПісля цього сервер працюватиме на порту 3000.
Для перевірки можна надіслати запити:
curl -i http://localhost:3000/users
curl -i -X POST http://localhost:3000/users
curl -i -X DELETE http://localhost:3000/users/3
curl -i http://localhost:3000/bad-request
curl -i http://localhost:3000/error
curl -i http://localhost:3000/unknownПрапорець -i показує не лише тіло відповіді, а й HTTP-код та заголовки.
Під час створення маршруту спочатку визначте результат операції:
Запит успішний?
200 — є результат у відповіді;
201 — створено новий ресурс;
204 — операція успішна, але тіла відповіді немає.
Проблема в запиті клієнта?
400 — неправильний або неповний запит;
401 — немає коректної автентифікації;
403 — доступ заборонено;
404 — ресурс не знайдено;
409 — конфлікт із поточним станом;
422 — дані мають правильний формат, але не проходять перевірку.
Проблема на сервері?
500 — непередбачена внутрішня помилка;
502 — помилка відповіді іншого сервера;
503 — сервіс тимчасово недоступний.
Код статусу має описувати саме результат HTTP-запиту, а не внутрішню назву помилки у програмі.
Клієнт може перевірити властивість ok у відповіді fetch. Вона має значення true для статусів від 200 до 299.
async function loadUsers() {
const response = await fetch('http://localhost:3000/users');
if (response.status === 404) {
console.log('Ресурс не знайдено');
return;
}
if (!response.ok) {
console.log(`Сталася помилка: ${response.status}`);
return;
}
const users = await response.json();
console.log(users);
}
loadUsers();Важливо: fetch не вважає відповіді 4xx або 5xx помилкою JavaScript автоматично. Запит може завершитися технічно успішно, але відповідь матиме невдалий HTTP-статус. Тому статус потрібно перевіряти самостійно.
200 для кожної відповідіЯкщо сервер повертає 200 навіть для помилок, клієнту складніше зрозуміти результат запиту.
Невдалий варіант:
HTTP/1.1 200 OK
{"error":"Користувача не знайдено"}Краще повернути 404:
HTTP/1.1 404 Not Found
{"error":"Користувача не знайдено"}500 для неправильних данихНеправильне введення користувача не є помилкою сервера. Для таких випадків використовуйте 400 або 422.
204Код 204 означає відсутність тіла відповіді. Якщо потрібно повернути JSON або текст, використовуйте 200.
401 і 403Якщо користувач не автентифікований — використовуйте 401. Якщо користувач автентифікований, але не має потрібних прав — 403.
Клієнт не повинен безумовно обробляти кожну відповідь як успішну. Потрібно перевіряти response.ok або конкретний response.status.
HTTP-код статусу описує результат обробки запиту.
Коди 2xx означають успіх:
200 — успішна відповідь;
201 — ресурс створено;
204 — успіх без тіла відповіді.
Коди 4xx описують проблеми в запиті клієнта:
400 — неправильний запит;
401 — відсутня автентифікація;
403 — доступ заборонено;
404 — ресурс не знайдено;
409 — конфлікт;
422 — дані не проходять перевірку.
Коди 5xx описують проблеми на сервері:
500 — внутрішня помилка;
502 — неправильна відповідь залежного сервера;
503 — сервіс тимчасово недоступний.
У Node.js статус можна встановити через response.statusCode або response.writeHead().
Клієнт має перевіряти HTTP-статус, навіть якщо сам HTTP-запит завершився без помилки JavaScript.