Модель ошибок

API возвращает стандартные HTTP-статусы с единым JSON-конвертом ошибки. Ошибки валидации несут детали по полям, доменные ошибки — машиночитаемый код.

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

{
  "error": "Bad Request",
  "message": "The request contains invalid parameters or malformed data",
  "code": 400,
  "details": [
    { "field": "email", "message": "Invalid email format" }
  ]
}

• error — краткое имя ошибки (Bad Request, Unauthorized, Not Found…).
• message — человекочитаемое описание.
• code — HTTP-статус числом.
• details — ошибки по полям (для валидации 400): field + message.

HTTP-статусы

Машиночитаемые коды

У доменных ошибок помимо HTTP-статуса есть машиночитаемый код — по нему удобно ветвить логику:

Обработка ошибок

Проверяйте статус ответа и читайте code/details:

const res = await fetch(url, { headers });
if (!res.ok) {
  const err = await res.json();
  console.error(`${err.code} ${err.error}: ${err.message}`);
  for (const d of err.details ?? []) {
    console.error(`  ${d.field}: ${d.message}`);
  }
}

res = requests.post(url, headers=headers, json=body)
if not res.ok:
    err = res.json()
    print(f"{err['code']} {err['error']}: {err['message']}")
    for d in err.get("details", []):
        print(f"  {d['field']}: {d['message']}")

Когда повторять запрос

• 5xx и сетевые сбои — повторяйте с экспоненциальной задержкой. Переводы повторяйте с тем же idempotencyKey, чтобы не задвоить платёж (см. Идемпотентность).
• 400 / 422 — не повторяйте вслепую: исправьте запрос по details.
• 403 — это решение Policy Engine. Смотрите reason и trace, чтобы понять, какая политика заблокировала (см. Policy Engine).

Что дальше