Помилки та конвенції

Один конверт помилки, 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, що й той, якого ніколи не було. Id не промацуються; не трактуйте 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.