/v1 з помилкою має формат application/problem+json (RFC 9457) із фіксованим набором полів:
code, а не за detail — code є стабільним машинним контрактом, тоді як detail призначене для читання людиною і може змінюватися. param присутнє, якщо помилку можна віднести до конкретного параметра запиту. Під час звернення до служби підтримки вказуйте request_id.
Коди помилок
Набір кодів є закритим: нові коди означають зміну публічного контракту й оголошуються через журнал змін API. Відповідь
retryable: true означає, що проблема може зникнути, але не доводить, що операція запису не мала жодного ефекту. Повторюйте запити на читання зі скінченною кількістю спроб і обмеженим часом, використовуючи експоненційну затримку та джитер. Дотримуйтеся Retry-After, якщо воно присутнє, зокрема у відповіді 409 або 429, які можна повторити.
Для операцій зміни дотримуйтеся задокументованого контракту ідемпотентності та відновлення для цієї операції. Якщо це підтримується, зберігайте початковий ключ і початковий запит. Не створюйте новий ключ після тайм-ауту або 5xx: це може призвести до повторення вже успішного запису. Заголовок Idempotency-Key не забезпечує захисту для операції, яка його не підтримує.