Ошибки и статусы

единый контракт тела ошибки

Ниже — единственный допустимый набор полей. Других корневых ключей в ответах с ошибкой для интеграции не закладывайте.

• message ( string) — обязательно, если тело JSON; человекочитаемое описание для логов и UI.
• code (string) — опционально; стабильный машинный код (аутентификация, бизнес-конфликт и т.п.). Если ключа нет — опирайтесь на message и HTTP.
• errors (object) — опционально; только при ошибке валидации полей: ключ — имя поля, значение — массив строк сообщений. Если ключа нет — это не ошибка «по полям».

Опциональные поля не присылаются как null для «пустого случая» — ключ просто отсутствует в JSON.

нормативный JSON-шаблон

Любой ответ с ошибкой — это подмножество следующей схемы (все три ключа показаны вместе для ясности; в реальном ответе присутствует только нужное подмножество):

{
  "message": "<строка — всегда, если есть JSON-тело ошибки>",
  "code": "<строка — только если API вернул код>",
  "errors": { "<поле>": ["<сообщение>", "..."] }
}

Минимальный валидный ответ: { "message": "…" }.

примеры заполнения шаблона

Структурированная ошибка (есть code, нет errors):

{
  "message": "Неверная подпись запроса.",
  "code": "signature_invalid"
}

Ошибка валидации (есть errors, поле code может отсутствовать):

{
  "message": "The given data was invalid.",
  "errors": {
    "orderId": ["The order id field is required."]
  }
}

типичные HTTP-коды

• 401 / 403 — аутентификация — аутентификация.
• 400 / 422 — формат или поля (см. errors при наличии).
• 404 — ресурс не найден.
• 409 — конфликт (в т.ч. idempotency_key_conflict).
• 429 — слишком много запросов (rate limit); снизьте частоту или обратитесь в поддержку.
• 5xx — повтор с backoff для идемпотентных операций.