Ошибка ссылка

Все API Ошибки возвращают JSON Тело с Анной errors массивКаждый элемент несет a detail строка и, на некоторых конечных точках, машиночитаемый codeВалидация Неудачи перечисляют один элемент на поле.

Нормативное определение является §10 Спецификация протокола.

Ошибка, которая приходит как успех

Маршрутизация, лимиты и борьба с мошенничеством не отказывают в оплате HTTP Они создают ошибку. Транзакция и маркировка rejectedТаким образом, ответ является 201 Created С совершенно обычным Тело:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "rejected",
  "error_description": "terminal not found"
}

Код, который проверяет только код статуса, записывает неоплаченные заказы как оплаченные. Читать далее status на всех Ответ. rejected и failed - не переводить деньги; charged Это единственный урегулированный результат.

Формат ответа на ошибку

{
  "errors": [
    { "code": "flow_not_continuable", "detail": "status_poll" }
  ]
}

Несколько конечных точек, предшествовавших этому формату ответа с '{"ошибка": "...", "сообщение": Вместо этого примите обе формы.

HTTP коды состояния

Код	Значение	Общая причина
`400`	Плохой запрос	несовершенный JSONОтсутствие необходимых полей и, в некоторых конечных точках, отсутствие поля. `x-organization-id` заголовок
`401`	несанкционированный	Недостающие или недействительные учетные данные

Коды ошибок транзакций

Они появляются в error_description в пределах полезных нагрузок webhook и ответов на статус транзакции:

Код	Значение	Рекомендуемые действия
`insufficient_funds`	Карта сократилась: недостаточно средств	Попросите плательщика использовать другую карту.
`card_declined`	Карта отклоняется эмитентом	Попросите плательщика связаться с банком
`expired_card`	Дата истечения срока действия карты прошла	Попросите плательщика обновить данные карты
`invalid_card_number`	Номер карты является недействительным	Формат номера контрольной карточки
`invalid_cvv`	CVV является неправильным	Попросите плательщика вернуться CVV
`do_not_honour`	Общий упадок банков	Попросите плательщика связаться с банком
`lost_card`	Карта потеряна	Не повторяйте
`stolen_card`	Карта была украдена	Не повторяйте
`restricted_card`	Карта не может быть использована для этой транзакции.	Попросите плательщика использовать другую карту.
`transaction_limit_exceeded`	Сумма превышает лимиты по карте/счету	Попросите плательщика использовать другой способ оплаты.
`3ds_failed`	3D-безопасная аутентификация провалилась	Попросите плательщика повторно использовать или использовать другую карту
`3ds_timeout`	3D-безопасное время	Повторите транзакцию
`provider_unavailable`	Поставщик платежей временно недоступен	Возвращение после задержки
`routing_failed`	Поставщика для этой сделки не нашли	Свяжитесь с оператором платформы
`duplicate_txid`	`txid` Уже существует этот терминал.	Используйте уникальный `txid` за транзакцию
`currency_not_supported`	Валюта, не поддерживаемая этим терминалом	Проверьте конфигурацию терминала
`amount_too_low`	Размер ниже минимального для данного провайдера	Увеличение суммы сделки
`amount_too_high`	Максимальная сумма для данного провайдера	Расщепление на более мелкие транзакции
`antifraud_reject`	Блокировка по правилам борьбы с мошенничеством	Свяжитесь с оператором платформы

Ошибки проверки ()422)

Ошибки проверки список один errors Каждый элемент проблемы, каждый с detail строка, обозначающая поле:

{
  "errors": [
    { "detail": "amount: can't be blank" },
    { "detail": "currency: is invalid" }
  ]
}

Обработка ошибок в вашем коде

Стратегия повторного использования

Тип ошибки	Повторить?	Заметки
`provider_unavailable`	► Да	Подожди. 30–60 секунды, максимум 3 повторные попытки
`3ds_timeout`	► Да	Повторите один раз сразу
`insufficient_funds`	❌ No	Показать альтернативный способ оплаты
`card_declined`	❌ No	Показать альтернативный способ оплаты
`lost_card`, `stolen_card`	Никогда	Не повторять и не представлять повторно
`duplicate_txid`	❌ No	Создайте новый уникальный `txid`
`routing_failed`	❌ No	Свяжитесь с оператором платформы

Пример обработки ошибок (Python)

import requests

response = requests.post(
    'https://4pay.online/api/v1/transactions',
    headers={
        'x-api-key': 'YOUR_API_KEY',
        'x-organization-id': '00000000-1111-2222-3333-444444444444',
        'Content-Type': 'application/json',
    },
    json={'params': {'type': 'payment', 'amount': '1000', 'currency': 'USD',
                     'txid': 'order-1', 'env': 'prod'}}
)

if response.status_code == 422:
    for err in response.json().get('errors', []):
        print(err.get('detail'))
elif response.status_code == 409:
    print("The transaction cannot move as requested from its current state")
elif response.status_code >= 500:
    print("Platform error — retry later or contact support")
else:
    tx = response.json()
    print(f"Transaction created: {tx['id']}")

Контактная поддержка

Постоянные ошибки или неожиданные 500 Ответы, контакты:

Электронная почта: помощница4pay.online
Включите сделку id (UUID) для более быстрой диагностики

Ошибка ссылка

Ошибка, которая приходит как успех​

Формат ответа на ошибку​

HTTP коды состояния​

Коды ошибок транзакций​

Ошибки проверки ()422)​

Обработка ошибок в вашем коде​

Стратегия повторного использования​

Пример обработки ошибок (Python)​

Контактная поддержка​