Обработка ошибок (Error Handling)

Partner API использует стандартные коды состояния HTTP и возвращает согласованные JSON-ответы об ошибках.

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

Все ошибки следуют этой структуре:

{
	"statusCode": 400,
	"message": "Validation failed",
	"error": "Bad Request"
}

Коды состояния

Код	Ошибка	Описание
`400`	Bad Request	Некорректное тело запроса, отсутствующие обязательные поля или ошибка валидации
`401`	Unauthorized	Отсутствующие, недействительные или просроченные учётные данные аутентификации
`403`	Forbidden	Действительные учётные данные, но недостаточно прав для данного действия
`404`	Not Found	Запрошенный ресурс не существует
`409`	Conflict	Обнаружен дублирующий запрос (например, дублирующий ключ идемпотентности с другим содержимым)
`429`	Too Many Requests	Превышен лимит запросов
`500`	Internal Server Error	На сервере произошла непредвиденная ошибка

Ошибки валидации

Для ошибок 400, вызванных валидацией запроса, поле message может содержать подробности о том, какие поля не прошли валидацию:

{
	"statusCode": 400,
	"message": [
		"products.0.productId must be a UUID",
		"products.0.startAt must be a valid ISO 8601 date",
		"payment.type must be one of: CARD, GOOGLE_PAY, APPLE_PAY, IDEAL, REVOLUT, BANCONTACT"
	],
	"error": "Bad Request"
}

Лучшие практики

Всегда проверяйте поле statusCode для определения категории ошибки.
При ошибках 401 проверьте API-ключ, актуальность метки времени (в пределах 5 минут), уникальность nonce и правильность вычисления подписи.
При ошибках 409 при создании заказа — исходный заказ уже был обработан. Получите его, используя ключ идемпотентности (idempotency key) или внешнюю ссылку.
При ошибках 500 повторите запрос с экспоненциальной задержкой. Если ошибка сохраняется, обратитесь в службу поддержки.