Ошибки и повторные запросы
Ошибки API имеют одинаковый формат. Код предназначен для логики приложения, сообщение — для пользователя. Интерфейс должен сохранять введённые данные и объяснять следующий шаг.
В этой статье
Единый ответ#
Ответ не содержит stack trace, SQL, токены или полный ответ внешнего провайдера. Не показывайте пользователю необработанные внутренние логи.
{
"error": {
"code": "GATEWAY_NOT_CONNECTED",
"message": "Денежные операции временно недоступны. Повторите позже или обратитесь в поддержку."
}
}Основные группы#
| HTTP | Типичные коды | Что делать |
|---|---|---|
| 400 | INVALID_JSON, UNKNOWN_FIELD, INVALID_INPUT | Исправить поля запроса |
| 401 | AUTH_REQUIRED, SESSION_EXPIRED | Войти повторно |
| 403 | INVALID_ORIGIN, CSRF_REQUIRED | Проверить origin и актуальную сессию |
| 404 | NOT_FOUND, TICKET_NOT_FOUND | Проверить адрес или принадлежность записи |
| 409 | CHALLENGE_UNAVAILABLE | Начать новый вход |
| 410 | CHALLENGE_EXPIRED | Создать новую ссылку входа |
| 413 | REQUEST_TOO_LARGE | Уменьшить тело |
| 415 | JSON_REQUIRED | Передать application/json |
| 429 | RATE_LIMITED | Снизить частоту и подождать |
| 503 | GATEWAY_NOT_CONNECTED, SERVICE_UNAVAILABLE | Проверить готовность интеграции или повторить позже |
Ограничение частоты#
| Действие | Лимит |
|---|---|
| Начало входа | 6 в минуту по хешу адреса |
| Проверка challenge | 90 в минуту на challenge |
| Вопрос к базе знаний | 12 в минуту по хешу адреса при D1 |
| Создание серверной ссылки | 20 в минуту на пользователя |
| Merchant API | 90 запросов в минуту на ключ |
| Новая заявка | 5 в сутки на пользователя |
| Продолжение заявки / решение модератора | 30 в минуту на пользователя для каждого действия |
| ИИ-обзор сайта | 30 в час на сервис |
| Чтение checkout и попытка оплаты | 90 в минуту по хешу адреса |
| Создание обращения | 6 в час на пользователя |
| Тест уведомления | 3 в час на пользователя |
| Генерация ИИ | 60 в час по умолчанию на весь сервис |
Что можно повторять#
Чтение состояния можно повторить с паузой при временной сетевой ошибке. Для изменений сначала проверьте, не выполнился ли исходный запрос: потеря ответа не доказывает отсутствие результата.
Денежные операции требуют идемпотентного ключа и проверки статуса на сервере. Клиентский переход на страницу результата не заменяет подтверждение операции.
Что приложить к обращению#
- Адрес страницы и действие перед ошибкой.
- Время, часовой пояс и видимый код ошибки.
- Идентификатор своего счёта или обращения, если он есть.
- Короткое описание ожидаемого результата.