Проверено 2026-11-10 · версия API 2026-11-09 · Читать Markdown
Ошибки, повторы и восстановление
Ошибки API используют { "error": { "code": "…", "message": "…", "requestId": "…" } }
с необязательными ошибками полей, ошибками назначений, подсказками повтора и передачами действий.
Сохраняйте requestId для поддержки. Не логируйте учетные данные, подписанные URL загрузок или
чувствительное содержимое запросов при сборе диагностики.
| Ответ | Восстановление |
|---|---|
401 unauthenticated | Проверьте отсутствующий, некорректный или отозванный ключ продукта |
403 forbidden_scope / account_not_allowed | Просмотрите права ключа и доступ к назначениям |
402 account_limit, seat_limit, storage_limit | Просмотрите права рабочего пространства и использование ресурсов |
402 subscription_inactive / trial_expired | Устраните состояние биллинга; сохраните черновики и работы в очереди |
409 revision_conflict | Прочитайте текущую версию, просмотрите изменения и намеренно примените их заново |
409 idempotency_conflict | Ключ был использован повторно с другим телом; сверьте исходную операцию |
409 consent_required | Попросите уполномоченного человека завершить предоставленную передачу на проверку |
409 too_late_to_cancel | Осмотрите фактический статус доставки; не заявляйте, что отмена удалась |
media_expired / media_deleting | Перезагрузите оригиналы и обновите черновик |
422 validation_failed | Исправьте структурированные поля или проблемы по назначениям |
429 rate_limited | Соблюдайте Retry-After; снизьте параллелизм и используйте задержки |
submission_unknown | Сверьте существующий внешний результат, прежде чем пытаться отправить снова |
Безопасные повторы мутаций
Сгенерируйте ключ идемпотентности перед первой мутацией и сохраните ее точный запрос.
Если ответ потерян, операция могла уже выполниться. Повторите
тот же запрос с тем же ключом; никогда не генерируйте новый ключ только потому, что
сеть выдала таймаут. Мутирующие инструменты MCP возвращают свой ключ, в том числе при
сбоях transport_outcome_unknown. Адаптер не повторяет мутации автоматически.
Технические лимиты скорости рабочего пространства — не кредиты на публикацию. Используйте /usage для
текущего тарифа и информации о лимитах запросов. Делайте задержки при временных ошибках, только когда
это уместно; повтор ошибок авторизации, проверки или согласия человека
без изменения их причины не помогает.
Частичный успех и наблюдение
Принятая партия публикации/планирования — это набор независимых доставок. Сохраняйте успешные квитанции и нативные ссылки. Восстановите неудавшееся назначение через его собственный эндпоинт повтора вместо повторного создания всей партии. Предпочитайте подписанные вебхуки; при опросе используйте ограниченное число попыток с нарастающими задержками и показывайте неразрешенную работу человеку.