Zpracování chyb (Error Handling)

Partner API používá standardní HTTP stavové kódy a vrací konzistentní JSON chybové odpovědi.

Formát chybové odpovědi

Všechny chyby mají tuto strukturu:

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

Stavové kódy

Kód	Chyba	Popis
`400`	Bad Request	Neplatné tělo požadavku, chybějící povinná pole nebo selhání validace
`401`	Unauthorized	Chybějící, neplatné nebo prošlé ověřovací údaje
`403`	Forbidden	Platné přihlašovací údaje, ale nedostatečná oprávnění pro tuto akci
`404`	Not Found	Požadovaný zdroj neexistuje
`409`	Conflict	Zjištěn duplicitní požadavek (např. duplicitní klíč idempotence s jiným payloadem)
`429`	Too Many Requests	Překročen limit požadavků
`500`	Internal Server Error	Na serveru došlo k neočekávané chybě

Validační chyby

U chyb 400 způsobených validací požadavku může pole message obsahovat podrobnosti o tom, která pole neprošla validací:

{
	"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"
}

Osvědčené postupy

Vždy zkontrolujte pole statusCode pro určení kategorie chyby.
U chyb 401 ověřte svůj API klíč, aktuálnost časového razítka (do 5 minut), jedinečnost nonce a výpočet podpisu.
U chyb 409 při vytváření objednávky byla původní objednávka již zpracována. Načtěte ji pomocí klíče idempotence nebo externí reference.
U chyb 500 opakujte s exponenciální prodlevou. Pokud chyba přetrvává, kontaktujte podporu.