Успех и ошибки

Как определить успешный ответ

Общая оболочка ответа бэкенда OrionMarketplace содержит три поля. Подтверждайте успех, только когда выполнены все три условия ниже.

• 200–299 — HTTP-запрос выполнен успешно.
• success_message !== null && success_message !== '' — Получено непустое сообщение об успехе.
• form_errors === null — Бэкенд не вернул ошибок формы.

{
  "form_errors": null,
  "success_message": "OK",
  "page_data": {}
}

Это пример оболочки ответа. Содержимое page_data зависит от эндпоинта; оно также может быть null. Не сравнивайте сообщение со строкой «OK»: текст переводится и может различаться.

Отсутствующее, пустое или равное null сообщение не подтверждает успех. Не показывайте завершение действия в этом случае. Ошибки имеют приоритет, даже если вместе с ними пришло сообщение об успехе. Отсутствие form_errors — некорректная оболочка, а не эквивалент null.

Как показать ошибки формы

Бэкенд OrionMarketplace может вернуть ошибки валидации и выполнения действия с HTTP 200. Всегда проверяйте оболочку JSON перед чтением результата или уведомлением об успехе.

{
  "form_errors": {
    "email": [
      {
        "message": "Введите корректный email.",
        "code": "invalid"
      }
    ],
    "__all__": [
      {
        "message": "Исправьте отмеченные поля.",
        "code": ""
      }
    ]
  },
  "success_message": null,
  "page_data": null
}

form_errors.email

Покажите каждое сообщение рядом с соответствующим полем ввода.

form_errors.__all__

Покажите эти сообщения над формой или в результате действия.

Каждому полю соответствует массив объектов message/code. Сохраните все сообщения, выводите их обычным текстом и не очищайте введённые пользователем данные. Код может быть пустым; не используйте переведённый текст сообщения как условие в программе.

HTTP-статусы

Эти статусы проверены в обработчиках API и middleware бэкенда OrionMarketplace. У одного статуса может быть несколько причин. Некоторые middleware и серверные ошибки возвращают HTML или обычный текст вместо общей оболочки JSON.

Текущий middleware проверяет квоту после выполнения эндпоинта. Ответ 453 не доказывает, что изменение было отменено. Проверьте результат перед повторной попыткой.

Ошибки шлюза и сети

502 / 503 — Шлюз витрины (src/routes/api/[...orionplace]/+server.ts) отвечает 502, если не удалось подключиться к OrionMarketplace, и 503, если настройки подключения отсутствуют или неверны. Обрабатывайте их отдельно от ошибок формы.

При обрыве соединения HTTP-ответа нет. Отдельно обрабатывайте неразбираемый JSON и неожиданный формат тела. Сохраняйте статус, если он получен, и не считайте, что любая ошибка соответствует оболочке API.

Когда показывать страницу ошибки

Заменяйте страницу, если не удалось загрузить необходимые для неё данные. Недоступность бэкенда не означает, что список товаров пуст или запрошенная страница не существует.

Сервер возвращает 503 и Cache-Control: private, no-store; при неуспешном переходе в браузере появляется тот же экран.

Справка об ошибках, инструкции по настройке, справочники типов и API-методов и обзор загрузки приложения доступны без инициализации. Ошибка последующего запроса формы не включает эту страницу.

Стартовый проект Svelte хранит ошибку загрузки приложения в store.failureⁱ, а store.statusⁱ равен error. Тогда любая страница витрины заменяется переведённой страницей ошибки с HTTP 503 и кнопкой «Повторить»; неизвестный адрес оставляет свою страницу 404. Таблица выше описывает, когда витрине нужно заменить страницу, а когда показать ошибку рядом с компонентом.

Обновление, ошибки и смена сессии

Обновление CSRF-cookie

POST /api/csrf_renew — отправьте пустой JSON-объект через шлюз магазина, чтобы получить или обновить CSRF-cookie. Затем прочитайте её текущее значение. Обновление CSRF не выполняет вход покупателя.

419 · page_data.csrf === false — так бэкенд сообщает об отказе проверки CSRF. Примите новые cookies ответа, при необходимости обновите токен и предложите повторить действие явно. Не повторяйте автоматически платежи, создание заказа и другие изменения.

403 — такой ответ также может означать недостаток прав или отклонённый источник запроса. Не считайте любой запрет доступа истёкшим CSRF-токеном.

После входа или выхода

reset() → await refresh() — после того как backend подтвердил вход или выход, вызовите reset() и await refresh() из useOrionplaceAppLoad(): данные и методы загрузятся заново для новой сессии.

src/lib/stores/orionplace.svelte.ts — сброс и обновление меняют данные приложения. Они не выполняют вход или выход и не удаляют cookies браузера.

Если сеанс завершился во время запроса

В стартовом проекте Svelte общий клиент из src/lib/utils/orionplace/api.ts проверяет каждый свой запрос, включая обновление CSRF, и так реагирует на HTTP 401: