Чтобы обработать ошибку сервера, сначала определите, что именно произошло: API вернул HTTP-ошибку, соединение не установлено или ответ нельзя прочитать. Затем приведите сбои к общей структуре, сопоставьте их с действиями пользователя и покажите короткое безопасное сообщение. Технические подробности сохраните в журнале, а повторный запрос предлагайте только тогда, когда он может помочь.
Короткий маршрут от сбоя API до понятного сообщения
- Разделите HTTP-ошибки, сетевые сбои и некорректные ответы: для них нужны разные сценарии.
- Преобразуйте ошибки в общую клиентскую структуру с типом, сообщением и признаком возможности повтора.
- Показывайте пользователю понятное действие, а не код ответа, текст исключения или данные сервера.
- Не повторяйте автоматически запросы, которые могут создать дубликат или требуют исправления введённых данных.
- Проверьте поведение интерфейса при недоступном сервере, пустом ответе и неверном формате.
Различайте HTTP-ошибку, сетевой сбой и неверный формат ответа
Такой подход подходит для разработки веб-приложений, где интерфейс получает данные через API и должен объяснять пользователю, что делать дальше. Он особенно полезен для форм, личных кабинетов и операций, которые меняют данные.
Не скрывайте ошибку успешным состоянием и не показывайте один и тот же текст для всех сбоев. Не запускайте автоматические повторы, пока не выяснили, безопасно ли повторять конкретный запрос.
- HTTP-ошибка: сервер ответил статусом, указывающим на проблему, например 400, 401, 403, 404, 409 или 500.
- Сетевой сбой: клиент не получил доступный HTTP-ответ - например, из-за отсутствия соединения или тайм-аута.
- Неверный формат: ответ пришёл, но его нельзя разобрать или он не соответствует ожидаемой структуре.
Статус 500 сам по себе не раскрывает причину сбоя. Запрос "ошибка 500 на сайте как исправить" требует проверки серверных журналов и инфраструктуры; на клиенте в это время следует показать нейтральное сообщение и предложить подходящее действие.
Приведите ошибки API к единой структуре на клиенте
Перед реализацией подготовьте договорённость между клиентом и сервером: какие статусы и поля ошибок используются, какие сообщения можно безопасно передавать пользователю и где искать технические детали. Для создания сайта под ключ эти правила стоит согласовать до того, как разные экраны начнут обрабатывать сбои по-своему.
- Доступ к коду клиентского приложения и описание API.
- Список ожидаемых кодов ответа и сценариев для каждого из них.
- Общий обработчик запросов или место, где ошибки приводятся к единому виду.
- Безопасное журналирование для диагностики без передачи секретов и персональных данных.
- Способ проверить интерфейс при ошибке: тесты, инструменты разработчика или тестовый сервер.
Например, можно нормализовать сбой в объект с полями kind, status, message, retryable и requestId. Поле message для интерфейса формируйте из доверенного словаря клиента, а не выводите без проверки содержимое ответа сервера.
Свяжите коды ответа с конкретными сценариями интерфейса
-
Определите тип сбоя.
После выполнения запроса отдельно проверьте HTTP-статус, сетевое исключение и возможность разобрать тело ответа. Не считайте любой ответ с некорректным JSON сетевой ошибкой. -
Нормализуйте результат.
Преобразуйте разные форматы ошибок в общий объект, чтобы экраны не зависели от особенностей конкретной конечной точки.- Для HTTP-ответа сохраните статус и проверенный код ошибки, если API его предоставляет.
- Для сетевого сбоя укажите, что ответ не получен.
- Для неверного формата зафиксируйте диагностический тип, не показывая пользователю содержимое ответа.
-
Сопоставьте ошибку с действием.
Для 401 предложите войти заново, для 403 объясните отсутствие доступа, для 404 сообщите, что объект не найден, а для 409 предложите обновить данные или разрешить конфликт. Для 400 покажите проверенные ошибки конкретных полей, если API передаёт их в согласованном формате. -
Обработайте сбой сервера и сети.
Для 5xx используйте сообщение о временной недоступности и предлагайте повторить позже, если операция безопасна. При сетевом сбое подскажите проверить соединение; не утверждайте, что сервер отклонил запрос, если ответа от него нет. -
Покажите состояние в нужном месте.
Ошибку поля формы разместите рядом с полем, сбой загрузки списка - в области списка, а отказ критической операции - рядом с её результатом. Сохраняйте введённые пользователем данные, если это безопасно. -
Запишите диагностические сведения.
Передайте в журнал тип сбоя, статус, контекст операции и идентификатор запроса, если он доступен. Не отправляйте в журнал пароли, токены и содержимое персональных данных без обоснованной необходимости.
Условный пример клиентской логики: если нормализованная ошибка имеет тип validation, покажите подсказку у поля; если unauthorized - предложите повторный вход; если network - сообщите, что ответ не получен. Так обработка ошибок в веб-приложении становится последовательной и предсказуемой.
Быстрый режим
- Разделите сбои на HTTP-ответ, отсутствие ответа и неверный формат.
- Преобразуйте их в единый объект ошибки.
- Свяжите тип ошибки с понятным сообщением и следующим действием.
- Проверьте сценарий и исключите небезопасные автоматические повторы.
Покажите пользователю причину сбоя без технических подробностей
Проверьте результат по списку. Сообщение должно объяснять ситуацию и давать выполнимый следующий шаг, не раскрывая внутреннее устройство сервера.
- Текст описывает проблему понятными словами, а не только статусом вроде 500.
- Сообщение не содержит трассировку, адреса внутренних сервисов, SQL-запросы или токены.
- Для ошибки формы указано, какое поле требует внимания и как его исправить.
- Для отказа в доступе предложен уместный шаг - например, войти в аккаунт или обратиться к администратору.
- При сетевом сбое интерфейс не выдаёт отсутствие ответа за подтверждённый отказ сервера.
- Если действие можно безопасно повторить, пользователю доступна понятная команда повтора.
- Введённые данные не пропадают без необходимости после сбоя.
- Технические детали доступны команде через защищённое журналирование, а не в пользовательском интерфейсе.
Добавьте повторный запрос там, где он действительно поможет
Повтор полезен при временном сбое или сетевом тайм-ауте, если операция безопасна для повторения. При ошибке в данных, отсутствии доступа или конфликте сначала требуется действие пользователя.
- Не повторяйте запрос автоматически после 400: сначала исправьте или уточните данные.
- Не используйте повтор как замену входу в аккаунт при 401.
- Не повторяйте операцию после 403, если права пользователя не изменились.
- При 409 сначала обновите данные или предложите разрешить конфликт.
- Не делайте безусловный автоматический повтор операции, которая может создать дубликат, например повторной отправки платежа или заказа.
- Не считайте любой тайм-аут доказательством того, что операция не выполнена: сервер мог обработать запрос, но ответ не дошёл до клиента.
- Не запускайте повтор без ограничения: он может усилить нагрузку при недоступности сервиса.
- Не показывайте кнопку повтора для постоянной ошибки, если пользователю сначала нужно изменить данные или права.
Если повтор безопасен, дайте пользователю явную кнопку или реализуйте ограниченную повторную попытку по правилам приложения. Для операций с изменением данных заранее согласуйте с API способ защиты от дублирования.
Проверьте обработку ошибок на отказах и некорректных ответах
Для проверки настройки обработки ошибок на сайте используйте несколько подходов - они дополняют друг друга:
- Модульные тесты: проверьте преобразование статусов, сетевых исключений и ошибок разбора ответа в единую структуру.
- Интеграционные тесты: убедитесь, что интерфейс показывает правильный текст и действие для основных сценариев API.
- Ручная проверка в браузере: проверьте отсутствие соединения, медленный ответ, серверную ошибку и ответ с неверным форматом.
- Тестовый сервер или имитация API: безопасно воспроизводите отказы, не создавая реальные платежи, заказы и другие значимые операции.
Во всех вариантах проверьте, что чувствительные сведения не попадают в сообщение пользователю, журнал или телеметрию без необходимости.
Сложные случаи при показе серверных ошибок
Можно ли показывать текст ошибки, который вернул API?
Только если формат и назначение этого поля согласованы, а сообщение проверяется на безопасность и понятность. Иначе используйте клиентский текст по типу ошибки, а ответ сохраняйте для диагностики с соблюдением правил защиты данных.
Что сообщать, если запрос завершился тайм-аутом?
Сообщите, что ответ не получен, и предложите проверить соединение или повторить действие, если оно безопасно. Для операции, которая могла выполниться на сервере, не заявляйте, что она точно не состоялась.
Нужно ли повторять запрос после ответа 500?
Не автоматически во всех случаях. Повтор уместен, когда операция безопасна для повторения и приложение ограничивает попытки; иначе покажите сообщение о временной проблеме и сохраните понятный путь к проверке результата.
Как обработать ответ с ошибкой, в котором нет JSON?
Считайте его ошибкой формата ответа, если API ожидало JSON, и используйте безопасное общее сообщение. Не показывайте пользователю сырой текст или HTML-страницу сервера.
Где показывать ошибку валидации?
Рядом с соответствующим полем, если API надёжно связывает ошибку с полем. Общую ошибку формы показывайте отдельно и не стирайте введённые данные без необходимости.
Что делать, если повторный запрос может создать дубликат?
Не повторяйте его вслепую. Сначала проверьте результат операции или используйте согласованный с API механизм защиты от повторного выполнения.
Какие сведения оставить для разработчика?
Запишите тип сбоя, статус, контекст операции и идентификатор запроса, если он есть. Исключите секреты и не передавайте чувствительные данные в журнал без необходимости.
Автор: Дмитрий Кузнецов