Ошибки и лимиты

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

Неуспешные запросы возвращают не‑2xx статус и JSON-тело:

{ "success": false, "error": { "code": "ORDER_INVALID_STATUS" } }

Ветвитесь по error.code (он стабилен), а не по человеческому сообщению.

Соответствие HTTP-статусов

HTTP	Когда
`400`	Неверный аргумент / нарушено предусловие (например, не тот статус).
`401`	Ключ отсутствует, неверен или отозван.
`403`	Ресурс не принадлежит вашему магазину.
`404`	Заказ/товар/чат не найден.
`409`	Конфликт / уже существует.
`429`	Превышен лимит запросов.
`5xx`	Бэкенд недоступен / внутренняя ошибка.

Частые коды ошибок

Код	Значение
`API_KEY_REQUIRED`	Ключ не передан.
`API_KEY_INVALID`	Ключ неверен или отозван.
`RATE_LIMIT`	Слишком много запросов с этим ключом.
`ORDER_NOT_FOUND`	Нет такого заказа в вашем магазине.
`ORDER_INVALID_STATUS`	Действие недопустимо из текущего статуса.
`ORDER_PERMISSION_DENIED`	Заказ/товар не вашего магазина или без автоматизации.
`CHAT_NOT_FOUND`	У заказа нет чата.
`CHAT_EMPTY_MESSAGE`	Пустой текст сообщения.
`VALIDATION_ERROR`	Тело запроса не прошло валидацию.
`SERVICE_UNAVAILABLE`	Нет доступного бэкенда, повторите позже.

Rate limiting

Лимиты применяются по API-ключу в скользящем окне. В ответах приходят RateLimit-Limit, RateLimit-Remaining и RateLimit-Reset. При 429 подождите сброса окна и повторите.

Не опрашивайте GET /v1/orders в плотном цикле. Поллите с разумным интервалом; push-вебхук на новые заказы запланирован.

Ретраи и идемпотентность

Сетевые ошибки и 5xx/429 безопасно повторять. Для мутаций (take, deliver, cancel) всегда отправляйте стабильный Idempotency-Key, чтобы повтор не сработал дважды.