Ошибки и конвенции

Один конверт ошибки, correlation id, оптимистичная блокировка, пагинация и другие правила, которым подчиняется каждый вызов.

Конверт ошибки

Каждый не-2xx ответ имеет ровно одну форму:

{
  "error": {
    "code": "PROVIDER_NOT_FOUND",
    "message": "Provider 'unknown' was not found",
    "details": {},
    "correlation_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }
}

Ветвитесь по code, никогда по message — формулировки меняются, коды нет. Полная таблица живёт в Error Codes. details может нести структурированный контекст; ошибки валидации кладут указатели на поля в details.errors, никогда не эхо-повторяя отправленные вами значения.

404 — это ещё и ответ о владении

Credential, который существует, но принадлежит кому-то другому, возвращает тот же 404 CREDENTIAL_NOT_FOUND, что и никогда не существовавший. Идентификаторы непрощупываемы; не трактуйте 404 как «повторить позже».

Correlation id

Отправьте X-Correlation-ID со своим собственным id запроса — или он будет сгенерирован за вас; в любом случае ответ несёт его обратно, а audit-лента его записывает. Указывайте его, сообщая о проблемах. На resolve id едет в теле запроса (correlation_id) и имеет приоритет над заголовком.

Оптимистичная блокировка

Каждая мутация сохранённого credential (PATCH, make-default, disable, enable) требует текущей version записи — в теле, а для PATCH альтернативно как If-Match: "3". Устаревшая версия отвечает 409 CREDENTIAL_VERSION_CONFLICT: перечитайте, затем повторите. DELETE — исключение: версия ему не нужна, а повтор на собственной уже удалённой записи — идемпотентный 204.

Запросы и ответы

Только JSON (Content-Type: application/json); тела запросов ограничены 64 KiB (сверх — 413 REQUEST_TOO_LARGE).
Неизвестные поля тела отклоняются: 400 INVALID_REQUEST, а не молчаливое игнорирование.
UUID — в канонической текстовой форме нижним регистром; таймстемпы — RFC 3339 UTC (2026-08-12T12:30:00Z).
Списки пагинируются через limit (по умолчанию 50, максимум 200) и offset; ответы несут total.
Ответы с масками credentials отправляются с Cache-Control: no-store — не кэшируйте их.
Нарушения схем секретного/конфигурационного объектов — 422 с выделенными кодами; всё остальное некорректное — 400. См. cookbook по валидации.

Доступность

503 SERVICE_NOT_READY означает, что зависимость (база данных, keyring шифрования) лежит — те же факты сообщает GET /health/ready. Повторите после того, как readiness вернёт ok; см. health-эндпоинты.