Области и ошибки

Каждая операция публичного API требует одну явную область. Валидные учётные данные без этой области получают 403 insufficient_scope; они никогда не повышаются молча до более широкого доступа.

Справочник областей#

Используйте области чтения для задач отчётности. Добавляйте область записи только когда интеграция выполняет эту мутацию. Например, экспорту заявок обычно нужны sites:read и leads:read, а не sites:write или agents:write.

Сбои областей#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

Создайте замещающий ключ с недостающей областью и обновите серверный секрет. Области существующего ключа API нельзя расширить на месте; это делает изменения привилегий явными и аудируемыми.

Оболочка ошибок#

Все ошибки API используют одну форму верхнего уровня:

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

Ветвитесь на error.code, а не на английском message. Сообщения могут улучшаться без смены версии. Логируйте error.request_id и заголовок ответа x-request-id с именем операции, статусом и попыткой повтора — но никогда не логируйте заголовок авторизации или секреты запроса.

Справочник статусов и кодов#

Ресурсы вне аккаунта владельца учётных данных могут возвращать 404 вместо раскрытия, существует ли ID другого арендатора.

Детали валидации#

Валидация полей возвращает пути, которые можно показать рядом с вашими собственными элементами формы:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

Тела мутаций должны быть объектами JSON. Массивы, пустые тела, данные формы и JSON, отправленный с текстовым типом контента, отклоняются.

Решения о повторе#

• Повторяйте 429 после числа секунд в Retry-After.
• Повторяйте 500 только для безопасных чтений или записей, защищённых тем же Idempotency-Key.
• Повторяйте идемпотентный 409 в процессе после его заголовка Retry-After: 2.
• Не повторяйте 400, 401, 403, 404 или конфликт состояния, пока причина не изменится.

См. Лимиты частоты для поведения отката и Справочник API для требуемой области каждой операции.