Справка

Коды ошибок

Ошибка — HTTP 4xx или 5xx и application/problem+json (RFC 9457) с машинным кодом в поле code: ветвитесь по нему, не по тексту.

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

problem+json

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "Касса 42 не найдена",
  "code": "DEVICE_NOT_FOUND"
}

HTTP	code	Когда
400	`INVALID_REQUEST`	Неверный JSON или параметры; что не так — в detail
401	`UNAUTHORIZED`	Нет или неверный X-Api-Key
402	`TRIAL_LIMIT`	Пробный тариф: чеков в этом месяце больше лимита — подключите подписку в кабинете
403	`FORBIDDEN`	Действие недоступно этому ключу
403	`KEY_READ_ONLY`	Ключ или вход «только чтение»: изменения касс, команды, прокси (кроме GET) и чеки недоступны
403	`DEVICE_DISABLED`	Касса выключена в аккаунте (`PATCH /api/v1/devices/{id}` disabled=true): команды и прокси ей не передаются; для чека — 409
404	`DEVICE_NOT_FOUND`	Кассы нет или она принадлежит другому аккаунту
404	`NOT_FOUND`	Нет чека или адреса
409	`IDEMPOTENCY_KEY_REUSED`	Ключ уже использован для другого чека
429	`RATE_LIMITED`	Лимит запросов к агентам — подождите Retry-After
503	`NOT_CONNECTED`	Касса не на связи (команда или прокси); Retry-After — когда повторить
504	`TIMEOUT`	Касса не ответила — повторите с тем же ключом идемпотентности

Ошибки прокси к API агента (/agent/api/v1/** и команды) приходят ещё и с заголовком X-Hw-Proxy-Error — см. API агента → Через облако.