Коды ошибок

Формат

Все отказы приходят в одном виде, без исключений:

{
  "error": "terminal_offline",
  "message": "постамат не на связи",
  "detail": "последний раз выходил на связь 10.10.2026, 11:42",
  "request_id": "01JA7F3K9P2QWERTYUIOPASDFG"
}

Поле	Для кого
error	для кода. По нему ветвитесь. Не меняется внутри v1
message	для человека: короткое объяснение
detail	для человека: подробности. Есть не всегда
request_id	для нас: назовите его в письме, и мы найдём этот запрос

Разбирайте error, а не message: текст сообщения мы вправе улучшать, машинный код — нет.

HTTP-коды

Код	Смысл
400	тело запроса не прошло проверку
401	ключ не передан, отозван либо неверен
403	ключу не хватает уровня: read там, где нужен write
404	своего такого нет (чужое тоже 404)
409	состояние не позволяет: ячейка заблокирована, машина молчит
429	превышена частота
500	наша поломка — пришлите request_id
503	связь с постаматами временно недоступна

Машинные коды

error	HTTP	Когда и что делать
bad_request	400	Поле не прошло проверку. Что именно — в detail
unauthorized	401	Ключ не передан, отозван либо неверен. Проверьте заголовок Authorization: Bearer …
insufficient_scope	403	Ключ только на чтение. Для открытия ячеек нужен ключ с правом записи
terminal_not_found	404	Постамата с таким кодом нет либо он принадлежит другой компании
cell_not_found	404	Ячейки с таким номером нет у этого постамата
command_not_found	404	Команды нет либо она принадлежит другой компании
cell_locked	409	Ячейка заблокирована оператором. Причина в detail
cell_service	409	Ячейка служебная: открывается только нашим оператором
terminal_offline	409	Постамат не на связи. Время последней связи в detail
rate_limited	429	Превышена частота. Сколько ждать — в заголовке Retry-After
broker_unavailable	503	Связь с постаматами временно недоступна. Повторите позже
internal	500	Наша поломка. Пришлите request_id на info@tetrabox.ru

Ещё два кода — not_found и conflict — приходят редко: это запасные значения для случаев, которым не назначен свой код. Обрабатывайте их так же, как 404 и 409 соответственно.

Что повторять, а что нет

Повторять можно (ошибка временная):

• 429 — через Retry-After секунд;
• 503 — с задержкой, увеличивая её: 5 с, 30 с, 2 мин;
• 500 — один раз, затем писать нам.

Повторять бесполезно (не изменится само):

• 400, 401, 403, 404 — запрос надо исправить;
• cell_service — эта ячейка не откроется никогда.

Особый случай — terminal_offline. Машина может вернуться на связь через минуту, а может стоять обесточенной до приезда человека. Бесконечно повторять нельзя: показывайте человеку, что постамат недоступен, и дайте кнопку повторить вручную.

Проверка ввода

При 400 в detail перечислены все претензии через точку с запятой:

{
  "error": "bad_request",
  "message": "в запросе есть ошибки",
  "detail": "ttl_seconds must not be greater than 300",
  "request_id": "01JA7F3K9P2QWERTYUIOPASDFG"
}

Лишние поля в теле — тоже ошибка. Если прислать поле, которого нет в описании метода, запрос будет отклонён: property мусор should not exist. Это защита от опечаток в названиях полей — молча проигнорированное поле хуже отказа, потому что приложение будет думать, что передало значение.