Ошибки, лимиты и рекомендации интегратору

Control Plane старается возвращать предсказуемые и автоматизируемые ответы. Для интегратора это означает, что API можно спокойно использовать в CI/CD, provisioning‑скриптах и внутренних сервисах — если соблюдать несколько правил.

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

Публичные пользовательские ошибки возвращаются в JSON‑виде:

{
  "error": "...",
  "message": "...",
  "details": { ... }
}

Что обычно означают статус‑коды:

• 400 BadRequest — неверный payload, отсутствует обязательное поле, имя не прошло валидацию;
• 401 Unauthorized — токен отсутствует, неверен или просрочен;
• 403 Forbidden — scope или permissions токена не позволяют выполнить операцию;
• 404 NotFound — ресурс не найден либо скрыт фильтрами доступа;
• 409 Conflict / LimitExceeded — конфликт состояния, ресурс уже существует или достигнут hard‑limit;
• 5xx — внутренняя ошибка платформы либо ошибка при взаимодействии с внутренними сервисами.

Отдельно полезно помнить про OperationDisabled: именно так Control Plane отвечает на ручные start/stop/scale и на поля start_immediately / initial_scale, которые в текущем пользовательском сценарии отключены.

Trial и PAYG

Для trial‑логики действуют hard limits:

• до 1 tenant;
• до 2 баз;
• до 10 CU·h compute;
• до 5 GiB egress.

На стороне продукта уже существует plan id standard_payg, а размерная модель готова к линейке L1–L5.

Что важно про размерный контракт

Для интегратора нужно честно разделять:

• пользовательскую размерную модель L1–L5;
• текущий активный autoscale runtime‑контракт L1/L2.

Это значит:

• приложение и UI уже могут оперировать полной размерной линейкой;
• в текущем живом writer handoff критично правильно поддерживается диапазон L1 <-> L2.

Что важно про describe API

Для БД теперь полезно читать не только state, но и новые поля:

• current_profile
• target_profile
• candidate_profile
• scale_state
• freeze_new_checkouts
• scale_failure_reason

Для интеграции это важно, потому что:

• можно отличить обычный cold start от profile handoff;
• можно увидеть controlled freeze/drain;
• можно корректно диагностировать failed cutover.

Правила для интегратора

1. Считайте create и delete асинхронными операциями.
   Сразу после запроса ресурс может быть ещё не в финальном состоянии.

2. Не стройте automation вокруг ручного lifecycle.
   В текущем managed‑сценарии правильный путь — auto‑start при подключении и auto‑stop по idle.

3. Сохраняйте tenant credentials и dsn_template сразу.
   Это базовые данные для подключения любого приложения.

4. Учитывайте scope и permissions токена.
   Большинство неожиданных 403 связано именно с этим.

5. Не привязывайтесь к worker_id, candidate_worker_id и backend_addr как к бизнес‑идентификаторам.
   Это runtime‑поля, а не стабильный продуктовый контракт.

6. Ожидайте, что первое подключение к stopped‑базе дольше warm‑path.
   Это нормальная цена serverless‑модели.

7. Если вы используете describe/list для операционной логики, учитывайте scale_state.
   Иначе automation может ошибочно считать controlled handoff аварией.

Итог простой: лучший интеграционный сценарий в SPG99 — работать с сущностями account / tenant / database и позволять платформе автоматически делать orchestration, включая новый writer autoscaler.