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

При обработке запросов, содержащих невалидные параметры, некорректную подпись или выполняемых при нехватке средств на балансе, Syncra Merchant API V2 возвращает ошибку с соответствующим HTTP-кодом состояния и телом ответа в формате JSON.

Формат тела ошибки (Error Shape)

Все ошибки возвращаются в едином стандартизированном JSON-формате, описывающем саму ошибку и детализирующем её причины:

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "The request body failed to pass validation checks.",
    "details": [
      {
        "field": "amount",
        "description": "Amount must be a positive integer representing value in smallest currency units."
      }
    ]
  }
}

Структура ответа

• code (строка): Строковый код ошибки для программной обработки вашей системой (String Enum).
• message (строка): Понятное человеку описание причины ошибки на английском или русском языке.
• details (массив): Дополнительный список объектов, указывающих на конкретные невалидные поля (актуально для ошибок валидации INVALID_ARGUMENT).

Справочник кодов ошибок

API V2 транслирует gRPC коды состояния бэкенда в стандартные HTTP коды и специфические внутренние коды ошибок:

Ошибки аутентификации (UNAUTHENTICATED)

Причинами возврата HTTP-статуса 401 могут быть:

• Отсутствие обязательных заголовков: В запросе не переданы заголовки X-Merchant-Token, X-Signature или X-Timestamp.
• Истечение времени (Replay Attack Protection): Время, переданное в X-Timestamp, отличается от времени на сервере шлюза более чем на 300 секунд (5 минут). Проверьте синхронизацию времени (NTP) на вашем сервере.
• Несоответствие подписи: Результат хеширования HMAC-SHA256(timestamp.body, webhook_secret) на сервере не совпал с переданным в заголовке X-Signature. Проверьте, правильный ли секрет подписи вы используете и не форматируется ли JSON-тело после вычисления подписи.

Ошибки валидации (INVALID_ARGUMENT)

Этот код возвращается, если параметры запроса не соответствуют бизнес-правилам шлюза. Примеры:

• Значение amount отрицательное или равно нулю.
• Значение currency передано в неверном формате или не поддерживается.
• Длина idempotency_key превышает лимиты (макс. 128 символов) или содержит запрещенные символы.
• Реквизиты в target_requisite содержат невалидный формат (буквенные символы в номере карты, неверный формат телефона для СБП).
• Передан некорректный адрес криптовалютного кошелька для вывода средств в USDT.