Ошибки и ретраи

Формат ошибки

Ошибка возвращается с HTTP-статусом и JSON-телом. Код бизнес-ошибки передаётся в поле message, отдельного поля code у бизнес-ошибок нет:

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "ORDER_NOT_FOUND"
}

Поле	Описание
statusCode	HTTP-статус
error	Стандартное название HTTP-статуса
message	Код бизнес-ошибки из каталога ниже или текстовое описание
code	Есть только у ошибок валидации (FST_ERR_VALIDATION) и других технических ошибок сервера

Ошибка валидации

Если запрос не прошёл проверку параметров, API возвращает 400. В message перечислены поля с ошибками — с указанием части запроса (body, querystring, params):

{
  "statusCode": 400,
  "code": "FST_ERR_VALIDATION",
  "error": "Bad Request",
  "message": "body/sendMessage Required"
}

Ошибка авторизации

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Unauthorized"
}

Ошибки интеграционного API

HTTP	message / code	Когда
400	code: FST_ERR_VALIDATION	Неверные параметры, тело или формат ID
401	Unauthorized	Нет заголовка Authorization: Bearer ... или токен пустой
404	ORDER_NOT_FOUND	Заявка не найдена или принадлежит другой компании: GET /order/{id}, GET /order/{id}/down-code, /up-code, /subtract-code
404	POSTOMAT_NOT_FOUND	Публичные эндпоинты: постомат с таким shortId не найден или у него нет координат
5xx	—	Ошибка на стороне сервера или временная недоступность

Каталог кодов ошибок

Полный список кодов бизнес-ошибок сервиса постоматов. Большинство из них возникает в сценариях, которые выполняются на самом постомате или в кабинетах InLog, а не в интеграционном API. Если ваша система логирует ошибки по коду, учитывайте весь список.

Код (message)	HTTP	Встречается в интеграционном API	Значение
ORDER_NOT_FOUND	404	да	Заявка не найдена
POSTOMAT_NOT_FOUND	404	да (публичные эндпоинты)	Постомат не найден
USER_NOT_FOUND	404	нет	Пользователь не найден
PASSWORD_NOT_CORRECT	404, 406	нет	Неверный пароль
WAIT	400	нет	Повторный запрос кода подтверждения слишком рано
CONFIRM_CODE_EXPIRED	400	нет	Срок действия кода подтверждения истёк
CONFIRM_CODE_NOT_VALID	400	нет	Неверный код подтверждения
TOKEN_NOT_VALID	400	нет	Недействительный токен сессии пользователя
USER_ALREADY_EXISTS	406	нет	Пользователь уже существует
PHONE_IS_BUSY	406	нет	Номер телефона уже занят
CELL_NOT_FOUND	404	нет	Ячейка не найдена
CELL_IS_BUSY	406	нет	Ячейка занята
CELL_ID_REQUIRED	400	нет	Не указана ячейка
TARIFF_NOT_FOUND	403	нет	Тариф не найден
INSUFFICIENT_FUNDS	403, 406	нет	Недостаточно средств на балансе
COMMAND_NOT_EXECUTE	500, 504	нет	Постомат не выполнил команду
ORDER_NOT_PAID	406	нет	Заявка не оплачена
ORDER_COMPLETED	406	нет	Заявка уже завершена
TRANSACTION_NOT_FOUND	404	нет	Платёжная транзакция не найдена
TRANSACTION_FAILED	404	нет	Платёжная транзакция не прошла

Повторные запросы

Ситуация	Повторять?	Как
Сетевая ошибка или таймаут на GET	да	С экспоненциальной задержкой
5xx на GET	да	С экспоненциальной задержкой, 3–5 попыток
429 Too Many Requests	да	Выждите время из заголовка Retry-After, если он есть, иначе — с экспоненциальной задержкой
400, 401, 404	нет	Исправьте запрос, токен или ID
Любая ошибка на POST /order/create	осторожно	См. ниже

Повтор создания заявки

API не удаляет дубликаты заявок: повторный POST /order/create после таймаута или 5xx может создать вторую заявку, даже если вы передаёте заголовок Idempotency-Key. Перед повтором проверьте, не создалась ли заявка: запросите GET /order/list и найдите заявку по своему идентификатору в customData.

Пример задержки: 400 мс, 800 мс, 1600 мс… с верхней границей 5 секунд. Такие значения по умолчанию используют SDK Node.js и SDK Java.