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

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

Любая ошибка — JSON с машинным кодом code и текстом message (по-английски, для журнала). Ошибки проверки данных содержат issues — какое поле и что не так:

{
  "code": "VALIDATION_FAILED",
  "message": "Request validation failed",
  "issues": [ { "path": "deliveryDate", "message": "YYYY-MM-DD" } ]
}

Коды

HTTP	code	Что делать
400	VALIDATION_FAILED	исправить данные по issues
400	REFERENCE_NOT_FOUND	ссылка на несуществующую запись (точку, склад)
400	INVALID_IDEMPOTENCY_KEY, INVALID_WEBHOOK_URL, INVALID_SCOPE	исправить запрос
401	UNAUTHENTICATED, INVALID_API_KEY	проверить ключ; не повторять без исправления
403	FORBIDDEN, API_KEY_NOT_ALLOWED	не хватает права — попросить администратора
404	—	записи нет (или она принадлежит другой компании — это неотличимо)
409	DUPLICATE (+field), PLAN_NOT_DRAFT, IDEMPOTENCY_IN_PROGRESS	конфликт данных
422	IDEMPOTENCY_KEY_REUSED	новый Idempotency-Key для нового содержимого
429	RATE_LIMITED	подождать Retry-After секунд
5xx	—	повторить с паузой (с тем же Idempotency-Key)

Лимиты

• 600 запросов в минуту на API-ключ (может меняться по тарифу). Каждый ответ содержит заголовки X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (секунд до сброса окна).
• Пакет заказов — до 1000 строк и до 1 МБ за запрос.
• Списки: limit до 500–1000 (см. справочник), постранично через offset.
• Вход пользователей: ограничения от подбора паролей (для интеграций не нужен — используйте ключ).

Повторы

• 429 — ждать Retry-After; 5xx и обрыв связи — повтор через 1, 2, 4, 8… секунд (не более 5 попыток), с тем же Idempotency-Key.
• 4xx (кроме 409 IDEMPOTENCY_IN_PROGRESS и 429) повторять бессмысленно — нужен другой запрос.