Понимание HTTP-кодов состояния: полное руководство

Каждый раз, когда вы загружаете веб-страницу, вызываете API или отправляете форму, ваш браузер и сервер общаются с помощью HTTP-кодов состояния. Эти трёхзначные числа — не просто загадочные цифры; они являются стандартизированным языком, который точно сообщает, что произошло с вашим запросом. Понимание HTTP-кодов состояния необходимо для отладки проблем с API, оптимизации веб-приложений и создания надёжных сервисов.

Что такое HTTP-коды состояния?

HTTP-коды состояния — это трёхзначные числа, возвращаемые сервером в ответ на HTTP-запрос клиента. Они указывают, был ли запрос успешным, перенаправленным или неудачным, и почему. Коды состояния определены в RFC 7231 и RFC 6585 и сгруппированы в пять классов на основе первой цифры.

1xx: Информационные

Каждый HTTP-код состояния состоит из трёх цифр. Первая цифра определяет класс ответа: 1xx для информационных, 2xx для успеха, 3xx для перенаправления, 4xx для ошибок клиента и 5xx для ошибок сервера. Последние две цифры предоставляют конкретную информацию в рамках этого класса.

• Используйте правильные коды состояния: возвращайте 201 для создания ресурса, 400 для некорректного ввода, 404 для ненайденных ресурсов и 409 для конфликтов. Семантическая согласованность делает ваш API интуитивно понятным.
• Включайте тела ошибок: при возврате кодов ошибок 4xx и 5xx всегда включайте тело ответа JSON с полями error, message и details. Это помогает клиентам понять, что пошло не так, и как это исправить.
• Будьте последовательны: используйте одни и те же коды состояния для одних и тех же ситуаций во всех конечных точках. Не возвращайте 400 для ошибок валидации в одной конечной точке и 422 в другой.

2xx: Успех

Коды 1xx указывают, что запрос получен и обработка продолжается. Они редко встречаются в повседневной веб-разработке, поскольку обычно обрабатываются прозрачно браузерами и HTTP-клиентами. Наиболее заметным является 101 Switching Protocols, используемый при обновлении WebSocket.

• Используйте 404 для соображений безопасности: когда пользователь не должен знать, существует ли ресурс, возвращайте 404 вместо 403. Это предотвращает перебор URL для обнаружения скрытых ресурсов.
• Избегайте 200 для ошибок: никогда не возвращайте 200 OK с телом ошибки. Это нарушает протокол HTTP и ломает кэши, прокси и инструменты мониторинга.
• Не раскрывайте трассировки стека: в ответах об ошибках никогда не включайте трассировки стека, пути к файлам или конфигурацию сервера. Это раскрывает внутренние данные злоумышленникам.
• Используйте общие сообщения: для производственных ошибок 500 используйте общие сообщения, такие как «Произошла внутренняя ошибка сервера». Регистрируйте детали внутренне для отладки.

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

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

• Различайте 401 и 403: всегда различайте неаутентифицированные запросы (401) и неавторизованные запросы (403). Это помогает клиентам понять, нужно ли им войти или запросить доступ.
• Устанавливайте заголовки Retry-After: при возврате 429 (Too Many Requests) или 503 (Service Unavailable), всегда включайте заголовок Retry-After, указывающий, когда клиент может повторить попытку. Это предотвращает каскадные повторные попытки.
• Избегайте пользовательских кодов состояния: используйте только стандартные коды состояния HTTP. Пользовательские коды, такие как 499 или 599, не являются стандартными и могут вести себя непредсказуемо с прокси, балансировщиками нагрузки и HTTP-клиентами.
• Если пользовательские коды необходимы, используйте нестандартные коды, такие как 499 (используется nginx для закрытия клиента) или 599 (используется некоторыми прокси), только если ваша инфраструктура уже их поддерживает.
• Никогда не переопределяйте стандартные коды: не переопределяйте стандартные коды состояния пользовательскими значениями. Если вам нужно передать дополнительные данные, используйте заголовки ответа или тело ответа.

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

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

• 400 Bad Request: The server cannot process the request due to malformed syntax. Check your request parameters and headers.
• 401 Unauthorized: Authentication is required and has either not been provided or has failed. The user needs to log in.
• 403 Forbidden: The server understood the request but refuses to authorize it. Unlike 401, authentication will not help.
• 404 Not Found: The requested resource does not exist on the server. This is the most common error code and has significant SEO implications if not handled properly.
• 405 Method Not Allowed: The request method (GET, POST, PUT, etc.) is not supported for the requested resource.
• 429 Too Many Requests: The user has sent too many requests in a given time period. This is rate limiting, commonly used by APIs.

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

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

• 500 Internal Server Error: A generic error message when the server encounters an unexpected condition. Check server logs for the root cause.
• 502 Bad Gateway: The server was acting as a gateway and received an invalid response from the upstream server. Common with reverse proxies and CDNs.
• 503 Service Unavailable: The server is temporarily unable to handle the request, usually due to maintenance or overload. Use the Retry-After header to indicate when to try again.
• 504 Gateway Timeout: The server was acting as a gateway and did not receive a timely response from the upstream server.

Коды состояния в REST API

Коды 5xx указывают, что сервер не смог выполнить действительный запрос. Это ошибки на стороне сервера, и клиенты обычно не могут их исправить, кроме повторной попытки позже.

1. Check the status code: Identify whether it is a client error (4xx) or server error (5xx).
2. Review server logs: For 5xx errors, server logs contain the stack trace and error details.
3. Inspect request headers: Use browser developer tools to verify that your request includes correct headers, cookies, and authentication tokens.
4. Test with curl: Reproduce the request using curl to isolate whether the issue is with the client or server.
5. Check recent changes: Deployments, configuration updates, or DNS changes often cause status code errors.