Обработка на грешки

Партньорският API (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 ключ, актуалността на timestamp-а (в рамките на 5 минути), уникалността на nonce и изчисляването на подписа.
При грешки 409 при създаване на поръчка оригиналната поръчка вече е обработена. Извлечете я чрез ключа за идемпотентност (idempotency key) или външна референция.
При грешки 500 опитайте отново с експоненциално забавяне (exponential backoff). Ако грешката продължава, свържете се с поддръжката.