Ошибки, повтор команд и пагинация
API возвращает HTTP status и application/problem+json. Схема каждой ошибки доступна возле метода. 401 — ключ или scope, 403 — доступ автора, 404 — недоступный ресурс, 409 — конфликт version/Idempotency-Key или состояния, 429 — лимит, 503 — временная недоступность.
Idempotency-Key
Для команды выберите уникальный key, 8–160 символов: первый — буква или цифра, далее буквы, цифры, точка, подчёркивание, двоеточие или дефис. При timeout повторяйте тот же метод, URL, body и key. Другой body с тем же key даст 409; новый key может выполнить второй эффект. У read-only POST требования проверяйте по параметрам метода.
expectedVersion защищает от потерянного обновления. После 409 получите свежую карточку и явно пересоберите команду. Ответ receipt подтверждает принятую команду, а не завершение асинхронной доставки. Не повторяйте автоматически деньги или отправку новым ключом.
Лимиты
Бюджет Developer API отделён от browser session. При 429 следуйте Retry-After, при transient сбое используйте backoff; для write сохраняйте тот же key. Недоступность rate store закрывает ingress с 503. Коммерческий тариф и включённые модули проверяются отдельно.
Страницы данных
Для cursor-каталогов используйте limit (обычно 50, максимум 100) и nextCursor. Cursor непрозрачен и привязан к исходным фильтрам: не меняйте их между страницами. Пустая страница с nextCursor требует продолжения. Списки не являются моментальным снимком всей базы. Точные ограничения конкретного метода указаны в схеме.