Обробка помилок (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 при створенні замовлення — оригінальне замовлення вже було оброблене. Отримайте його за ключем ідемпотентності або зовнішнім посиланням.
Для помилок 500 повторіть запит з експоненціальним відкладенням. Якщо помилка зберігається, зверніться до служби підтримки.