API REST використовують частину рядка стану повідомлення HTTP-відповіді, щоб повідомити клієнтів про загальний результат їхнього запиту. RFC 2616 визначає синтаксис рядка стану, як показано нижче:
Рядок статусу = HTTP-версія SP Код стану SP Reason-Phrase CRLF
HTTP визначає ці стандартні коди стану, які можна використовувати для передачі результатів запиту клієнта. Коди стану поділяються на п’ять категорій.
- 1xx: Інформаційні – передає інформацію на рівні протоколу передачі.
- 2xx: Успішно – вказує на те, що запит клієнта прийнято успішно.
- 3xx: Перенаправлення – вказує на те, що клієнт повинен виконати деякі додаткові дії, щоб виконати свій запит.
- 4xx: Помилка клієнта – ця категорія кодів статусу помилки вказує пальцем на клієнтів.
- 5xx: Помилка сервера – сервер бере на себе відповідальність за ці коди статусу помилки.
- REST API – найбільш використовувані коди
1xx Коди статусу [Інформаційні]
| Код статусу | Опис |
|---|---|
| 100 Continue | Проміжна відповідь. Вказує клієнту, що початкова частина запиту була отримана і ще не була відхилена сервером. Клієнт СЛІД продовжити, надіславши решту запиту, або, якщо запит уже виконано, проігнорувати цю відповідь. Сервер ПОВИНЕН надіслати остаточну відповідь після виконання запиту. |
| 101 Switching Protocol | Надсилається у відповідь на заголовок запиту на оновлення від клієнта та вказує на протокол, на який перемикається сервер. |
| 102 Processing (WebDAV) | Вказує на те, що сервер отримав і обробляє запит, але відповіді ще немає. |
| 103 Early Hints | Передусім призначений для використання з Linkзаголовком. Це пропонує агенту користувача почати попереднє завантаження ресурсів, поки сервер готує остаточну відповідь. |
2xx Коди статусу [Успіх]
| Код статусу | Опис |
|---|---|
| 200 OK | Вказує на те, що запит виконано успішно. |
| 201 Created | Вказує на те, що запит виконано успішно, і в результаті створено новий ресурс. |
| 202 Accepted | Вказує на те, що запит отримано, але ще не виконано. Зазвичай він використовується для виконання запитів журналу та пакетної обробки. |
| 203 Non-Authoritative Information | Вказує на те, що повернута метаінформація в заголовку сутності не є остаточним набором, доступним із вихідного сервера, а зібрана з локальної або сторонньої копії. Представлений набір може бути підмножиною або надмножиною оригінальної версії. |
| 204 No Content | Сервер виконав запит, але не повинен повертати тіло відповіді. Сервер може повернути оновлену метаінформацію. |
| 205 Reset Content | Вказує клієнту скинути документ, який надіслав цей запит. |
| 206 Partial Content | Він використовується, коли використовуємо заголовок Range надсилаємий від клієнта для запиту лише частини ресурсу. |
| 207 Multi-Status (WebDAV) | Індикатор для клієнта, що відбулося кілька операцій і що статус кожної операції можна знайти в тілі відповіді. |
| 208 Already Reported (WebDAV) | Дозволяє клієнту повідомляти серверу, що той самий ресурс (з такою ж прив’язкою) згадувався раніше. Він ніколи не відображається як справжній код відповіді HTTP в рядку стану, а відображається лише в bodys. |
| 226 IM Used | Сервер виконав запит GET для ресурсу, і відповідь є представленням результату однієї або кількох маніпуляцій із екземпляром, застосованих до поточного екземпляра. |
Коди статусу 3xx [перенаправлення]
| Код статусу | Опис |
|---|---|
| 300 Multiple Choices | Запит має більше ніж одну можливу відповідь. Користувач-агент або користувач повинен вибрати один із них. |
| 301 Moved Permanently | URL запитуваного ресурсу змінено назавжди. Нова URL-адреса задається полем Location заголовка у відповіді. Цю відповідь можна кешувати, якщо не вказано інше. |
| 302 Found | URL запитуваного ресурсу тимчасово змінено. Нова URL-адреса задається полем Location у відповіді. Цю відповідь можна кешувати, лише якщо на неї вказано поле заголовка Cache-Control або Expires. |
| 303 See Other | Відповідь можна знайти за іншим URI, і потрібно отримати її за допомогою методу GET на цьому ресурсі. |
| 304 Not Modified | Вказує клієнту, що відповідь не було змінено, тому клієнт може продовжувати використовувати ту саму кешовану версію відповіді. |
| 305 Use Proxy (Deprecated) | Вказує, що запитана відповідь має бути доступна через проксі. |
| 306 (Unused) | Це зарезервований код статусу, який більше не використовується. |
| 307 Temporary Redirect | Вказує, що клієнт повинен отримати запитуваний ресурс за іншим URI за допомогою того самого методу, який використовувався в попередньому запиті. Це подібно до того, 302 Found за одним винятком, що буде використано той самий метод HTTP, який використовувався в попередньому запиті. |
| 308 Permanent Redirect (experimental) | Вказує, що ресурс тепер постійно розташований за іншим URI, указаним у Location заголовку. Це подібно до того, 301 Moved Permanently за одним винятком, що буде використано той самий метод HTTP, який використовувався в попередньому запиті. |
Коди стану 4xx (помилка клієнта)
| Код статусу | Опис |
|---|---|
| 400 Bad Request | Сервер не міг зрозуміти запит через неправильний синтаксис. Клієнт НЕ ПОВИНЕН повторювати запит без змін. |
| 401 Unauthorized | Вказує, що для запиту потрібна інформація для автентифікації користувача. Клієнт МОЖЕ повторити запит із відповідним полем заголовка авторизації |
| 402 Payment Required (Experimental) | Зарезервовано для майбутнього використання. Він призначений для використання в цифрових платіжних системах. |
| 403 Forbidden | Неавторизований запит. Клієнт не має прав доступу до контенту. На відміну від 401, ідентифікаційні дані клієнта відомі серверу. |
| 404 Not Found | Сервер не може знайти запитуваний ресурс. |
| 405 Method Not Allowed | Метод запиту HTTP відомий серверу, але його вимкнено та не може використовуватися для цього ресурсу. |
| 406 Not Acceptable | Сервер не знаходить жодного вмісту, який відповідає критеріям, заданим агентом користувача в заголовку Accept, надісланому в запиті. |
| 407 Proxy Authentication Required | Вказує, що клієнт повинен спочатку автентифікувати себе за допомогою проксі. |
| 408 Request Timeout | Вказує на те, що сервер не отримав повний запит від клієнта протягом виділеного сервером періоду очікування. |
| 409 Conflict | Запит не вдалося виконати через конфлікт із поточним станом ресурсу. |
| 410 Gone | Запитуваний ресурс більше не доступний на сервері. |
| 411 Length Required | Сервер відмовляється прийняти запит без визначеної довжини вмісту. Клієнт МОЖЕ повторити запит, якщо він додає дійсне поле заголовка Content-Length. |
| 412 Precondition Failed | Клієнт вказав у своїх заголовках попередні умови, яким сервер не відповідає. |
| 413 Request Entity Too Large | Сутність запиту перевищує обмеження, визначені сервером. |
| 414 Request-URI Too Long | URI, який запитує клієнт, довший, ніж може інтерпретувати сервер. |
| 415 Unsupported Media Type | Запит типу медіа Content-type не підтримується сервером. |
| 416 Requested Range Not Satisfiable | Неможливо заповнити діапазон, указаний у полі заголовка Range у переданому запиті. |
| 417 Expectation Failed | Очікування, указане в полі заголовка Expect запиту, не може бути виконано сервером. |
| 418 I’m a teapot (RFC 2324) | Це було визначено як жарт квітня, і не очікується, що він буде реалізований реальними HTTP-серверами. ( RFC 2324 ) |
| 420 Enhance Your Calm (Twitter) | Повертається API пошуку Twitter і Trends, коли швидкість клієнта обмежена. |
| 422 Unprocessable Entity (WebDAV) | Сервер розуміє тип вмісту та синтаксис сутності запиту, але все одно сервер не може обробити запит з певної причини. |
| 423 Locked (WebDAV) | Ресурс, до якого здійснюється доступ, заблоковано. |
| 424 Failed Dependency (WebDAV) | Запит не виконано через помилку попереднього запиту. |
| 425 Too Early (WebDAV) | Вказує на те, що сервер не бажає ризикувати обробкою запиту, який може бути відтворений повторно. |
| 426 Upgrade Required | Сервер відмовляється виконувати запит. Сервер обробить запит після оновлення клієнта до іншого протоколу. |
| 428 Precondition Required | Початковий сервер вимагає, щоб запит був умовним. |
| 429 Too Many Requests | Користувач надіслав занадто багато запитів за певний проміжок часу («обмеження швидкості»). |
| 431 Request Header Fields Too Large | Сервер не бажає обробити запит, оскільки його поля заголовка завеликі. |
| 444 No Response (Nginx) | Сервер Nginx не повертає жодної інформації клієнту та закриває з’єднання. |
| 449 Retry With (Microsoft) | Запит потрібно повторити після виконання відповідної дії. |
| 450 Blocked by Windows Parental Controls (Microsoft) | Батьківський контроль Windows увімкнено та блокує доступ до вказаної веб-сторінки. |
| 451 Unavailable For Legal Reasons | Агент користувача запитував ресурс, який не може бути наданий законно. |
| 499 Client Closed Request (Nginx) | З’єднання закривається клієнтом, поки сервер HTTP обробляє свій запит, через що сервер не може надіслати заголовок HTTP назад. |
5xx Коди стану (помилка сервера)
| Код статусу | опис |
|---|---|
| 500 Internal Server Error | Сервер зіткнувся з несподіваною умовою, через яку він не міг виконати запит. |
| 501 Not Implemented | Метод HTTP не підтримується сервером і не може бути оброблений. |
| 502 Bad Gateway | Сервер отримав недійсну відповідь під час роботи як шлюз для отримання відповіді, необхідної для обробки запиту. |
| 503 Service Unavailable | Сервер не готовий обробити запит. |
| 504 Gateway Timeout | Сервер діє як шлюз і не може вчасно отримати відповідь на запит. |
| 505 HTTP Version Not Supported (експериментальний) | Версія HTTP, яка використовується в запиті, не підтримується сервером. |
| 506 Variant also Negotiates (експериментальний) | Вказує на те, що на сервері виникла внутрішня помилка конфігурації: вибраний варіант ресурсу налаштовано на участь у самому прозорому узгодженні вмісту, і тому він не є належною кінцевою точкою в процесі узгодження. |
| 507 Insufficient Storage (WebDAV) | Метод не вдалося виконати на ресурсі, оскільки сервер не може зберегти представлення, необхідне для успішного виконання запиту. |
| 508 Loop Detected (WebDAV) | Під час обробки запиту сервер виявив нескінченний цикл. |
| 510 Not Extended | Для виконання сервером запиту потрібні подальші розширення. |
| 511 Network Authentication Required | Вказує на те, що клієнт повинен пройти автентифікацію, щоб отримати доступ до мережі. |
6. Найбільш використовувані коди статусу HTTP REST
200 ОК
Це вказує на те, що REST API успішно виконав будь-яку дію, яку запитував клієнт, і що більш конкретний код із серії 2xx не підходить.
На відміну від коду статусу 204, відповідь 200 має містити тіло відповіді. Інформація, що повертається з відповіддю, залежить від методу, використаного в запиті, наприклад:
- GET сутність, що відповідає запитуваному ресурсу, надсилається у відповідь;
- HEAD поля заголовка сутності, що відповідають запитуваному ресурсу, надсилаються у відповідь без будь-якого тіла повідомлення;
- POST сутність, що описує або містить результат дії;
- TRACE — сутність, що містить повідомлення запиту, отримане кінцевим сервером.
201 Створено
API REST відповідає кодом стану 201 кожного разу, коли ресурс створюється в колекції. Також можуть бути випадки, коли новий ресурс створюється в результаті певної дії контролера, і в цьому випадку 201 також буде відповідною відповіддю.
На щойно створений ресурс можна посилатися за URI, які повертаються в об’єкті відповіді, при цьому найбільш конкретний URI для ресурсу вказується в полі заголовка Location.
Початковий сервер ПОВИНЕН створити ресурс перед поверненням коду статусу 201. Якщо дію неможливо виконати негайно, замість цього сервер ПОВИНЕН відповісти 202 (Прийнято).
202 Прийнято
Відповідь 202 зазвичай використовується для дій, які потребують багато часу для обробки. Він свідчить про те, що запит прийнято до обробки, але обробка не завершена. Зрештою запит може бути виконано або не виконано, або навіть може бути відхилено під час обробки.
Його мета полягає в тому, щоб дозволити серверу прийняти запит для якогось іншого процесу (можливо, пакетно-орієнтованого процесу, який виконується лише один раз на день), не вимагаючи, щоб підключення агента користувача до сервера зберігалося до завершення процесу.
Об’єкт, що повертається з цією відповіддю, ПОВИНЕН включати вказівку поточного статусу запиту та або вказівник на монітор стану (розташування черги завдань), або деяку оцінку того, коли користувач може очікувати, що запит буде виконано.
204 Немає вмісту
Код статусу 204 зазвичай надсилається у відповідь на запит PUT, POST, або , DELETEколи REST API відмовляється надіслати будь-яке повідомлення про стан або представлення в тілі повідомлення відповіді.
API також може надіслати 204 разом із запитом GET, щоб вказати, що запитуваний ресурс існує, але не має представлення стану для включення в тіло.
Якщо клієнт є користувальницьким агентом, йому НЕ ПОВИННО змінювати вигляд документа на той, який викликав надсилання запиту. Ця відповідь насамперед призначена для того, щоб дозволити введення для виконання дій, не спричиняючи зміни до активного перегляду документа агента користувача. Однак будь-яку нову або оновлену метаінформацію СЛІД застосовувати до документа, який зараз знаходиться в динамічному поданні агента користувача.
Відповідь 204 НЕ ПОВИННА містити тіло повідомлення, тому завжди завершується першим порожнім рядком після полів заголовка.
301 Переміщено назавжди
Код статусу 301 вказує на те, що ресурсну модель REST API було значно перероблено, а запитуваному клієнтом ресурсу призначено новий постійний URI. REST API має вказати новий URI у заголовку Location відповіді, і всі майбутні запити мають бути спрямовані на вказаний URI.
Ви навряд чи використовуватимете цей код відповіді у своєму API, оскільки ви завжди можете використовувати версії API для нового API, зберігаючи старий.
302 Знайдено
Код статусу відповіді HTTP 302 Знайдено є поширеним способом виконання переспрямування URL-адреси. HTTP-відповідь із цим кодом статусу додатково надасть URL-адресу в полі заголовка Location. Агент користувача (наприклад, веб-браузер) запрошується відповіддю з цим кодом зробити другий. В іншому випадку ідентичний запит на нову URL-адресу, указану в полі розташування.
Багато веб-браузерів реалізували цей код у спосіб, який порушує цей стандарт, змінюючи тип нового запиту на GET, незалежно від типу, використаного в оригінальному запиті (наприклад, POST). RFC 1945 і RFC 2068 вказують, що клієнту заборонено змінювати метод у перенаправленому запиті. Коди статусу 303 і 307 були додані для серверів, які хочуть однозначно вказати, яка реакція очікується від клієнта.
303 Дивись інше
Відповідь 303 вказує на те, що ресурс контролера завершив свою роботу, але замість надсилання потенційно небажаного тіла відповіді він надсилає клієнту URI ресурсу відповіді. Відповіддю може бути URI повідомлення про тимчасовий статус або URI якогось уже існуючого, більш постійного ресурсу.
Загалом, код статусу 303 дозволяє REST API надсилати посилання на ресурс, не змушуючи клієнта завантажувати його стан. Замість цього клієнт може надіслати запит GET до значення заголовка Location.
Відповідь 303 НЕ ПОВИННА кешуватися, але відповідь на другий (перенаправлений) запит може кешуватися.
304 Не змінено
Цей код статусу подібний до 204 («Немає вмісту») тим, що тіло відповіді має бути порожнім. Важлива відмінність полягає в тому, що 204 використовується, коли в тілі немає нічого для надсилання, тоді як 304 використовується, коли ресурс не було змінено з моменту версії, зазначеної в заголовках запиту If-Modified-Since або If-None-Match.
У такому випадку немає необхідності повторно передавати ресурс, оскільки клієнт усе ще має попередньо завантажену копію.
Використання цього заощаджує пропускну здатність і повторну обробку як на сервері, так і на клієнті, оскільки потрібно надсилати та отримувати лише дані заголовка порівняно з усією сторінкою, яка повторно обробляється сервером, а потім надсилати знову, використовуючи більшу пропускну здатність сервера та клієнта. .
307 Тимчасове перенаправлення
Відповідь 307 вказує на те, що REST API не збирається обробляти запит клієнта. Замість цього клієнт повинен повторно надіслати запит за URI, указаним у заголовку Location повідомлення відповіді. Однак майбутні запити все одно повинні використовувати вихідний URI.
REST API може використовувати цей код статусу, щоб призначити тимчасовий URI запитуваному клієнтом ресурсу. Наприклад, відповідь 307 може бути використана для передачі запиту клієнта на інший хост.
Тимчасовий URI СЛІД вказувати в полі Location у відповіді. Якщо метод запиту не був HEAD, сутність відповіді ПОВИННА містити коротку гіпертекстову примітку з гіперпосиланням на новий URI. Якщо код статусу 307 отримано у відповідь на запит, відмінний від GETабо HEAD, агент користувача НЕ ПОВИНЕН автоматично перенаправляти запит, якщо він не може бути підтверджений користувачем, оскільки це може змінити умови, за яких було видано запит.
400 Невірний запит
400 — це загальний статус помилки на стороні клієнта, який використовується, коли інший код помилки 4xx не підходить. Помилки можуть бути як-от неправильний синтаксис запиту, недійсні параметри повідомлення запиту або оманлива маршрутизація запиту тощо.
Клієнт НЕ ПОВИНЕН повторювати запит без змін.
401 Неавторизовано
Відповідь про помилку 401 вказує на те, що клієнт намагався працювати на захищеному ресурсі, не надавши належної авторизації. Можливо, він надав неправильні облікові дані або їх не було взагалі. Відповідь має містити поле заголовка WWW-Authenticate, що містить виклик, застосовний до запитуваного ресурсу.
Клієнт МОЖЕ повторити запит із відповідним полем заголовка авторизації. Якщо запит уже містив облікові дані авторизації, тоді відповідь 401 вказує на те, що в авторизації цих облікових даних було відмовлено. Якщо відповідь 401 містить той самий виклик, що й попередня відповідь, і агент користувача вже намагався автентифікуватися принаймні один раз, тоді користувачеві СЛІД надати сутність, яку було надано у відповіді, оскільки ця сутність може містити відповідну діагностичну інформацію.
403 Заборонено
Відповідь про помилку 403 вказує на те, що запит клієнта сформовано правильно, але REST API відмовляється його виконувати, тобто користувач не має необхідних прав доступу до ресурсу. Відповідь 403 не є випадком недостатніх облікових даних клієнта; це буде 401 («Неавторизовано»).
Автентифікація не допоможе, і запит НЕ СЛІД повторювати. На відміну від відповіді 401 Unauthorized, автентифікація не матиме значення.
404 Не знайдено
Код статусу помилки 404 вказує на те, що REST API не може зіставити URI клієнта з ресурсом, але може бути доступним у майбутньому. Наступні запити клієнта допустимі.
Немає вказівок на те, чи є цей стан тимчасовим чи постійним. Код статусу 410 (Зникло) СЛІД використовувати, якщо сервер знає через якийсь внутрішній настроюваний механізм, що старий ресурс постійно недоступний і не має адреси пересилання. Цей код статусу зазвичай використовується, коли сервер не бажає точно розкривати, чому запит було відхилено, або коли немає іншої відповіді.
405 (метод заборонений)
API відповідає помилкою 405, яка вказує на те, що клієнт намагався використати метод HTTP, який ресурс не дозволяє. Наприклад, ресурс лише для читання може підтримувати лише GET і HEAD, тоді як ресурс контролера може дозволяти GET і POST, але не PUT або DELETE.
Відповідь 405 має містити заголовок Allow, у якому перераховано методи HTTP, які підтримує ресурс. Наприклад:
Allow: GET, POST
406 (неприйнятно)
Відповідь про помилку 406 вказує на те, що API не може створити будь-який із бажаних типів мультимедійних даних клієнта, як зазначено в заголовку запиту Accept. Наприклад, запит клієнта на дані, відформатовані як application/xml, отримає відповідь 406, якщо API хоче форматувати дані лише як application/json.
Якщо відповідь може бути неприйнятною, агент користувача МАЄ тимчасово припинити отримання додаткових даних і запитати у користувача рішення щодо подальших дій.
412 (попередня умова не виконана)
Відповідь про помилку 412 вказує на те, що клієнт вказав одну або кілька попередніх умов у своїх заголовках запиту, фактично повідомляючи REST API виконувати його запит лише за умови виконання певних умов. Відповідь 412 вказує на те, що ці умови не виконано, тому замість виконання запиту API надсилає цей код статусу.
415 (тип носія не підтримується)
Відповідь про помилку 415 вказує на те, що API не може обробити наданий клієнтом медіа-тип, як зазначено в заголовку запиту Content-Type. Наприклад, запит клієнта, що містить дані у форматі як application/xml, отримає відповідь 415, якщо API бажає обробляти лише дані у форматі application/json.
Наприклад, клієнт завантажує зображення як image/svg+xml, але сервер вимагає, щоб зображення використовували інший формат.
500 Внутрішня помилка сервера)
500 — це загальна відповідь на помилку REST API. Більшість веб-фреймворків автоматично відповідають цим кодом статусу відповіді щоразу, коли вони виконують код обробника запитів, який викликає виняткову ситуацію.
Помилка 500 ніколи не є провиною клієнта, і тому для клієнта розумно повторити той самий запит, який викликав цю відповідь, і сподіватися отримати іншу відповідь.
Відповідь API – це загальне повідомлення про помилку, яке видається, коли виникла неочікувана умова, і більш конкретне повідомлення не підходить.
501 (не реалізовано)
Сервер або не розпізнає метод запиту, або не може виконати запит. Зазвичай це передбачає доступність у майбутньому (наприклад, нова функція API веб-сервісу).
- IANA Hypertext Transfer Protocol (HTTP) Status Code Registry