Každá API integrace dříve nebo později narazí na chyby. Výpadek sítě, nedostupný server, nesprávně formátovaný dokument: to patří k věci. PSB API komunikuje chyby prostřednictvím standardních HTTP stavových kódů a strukturovaných JSON odpovědí. Navíc PSB má zabudovaný retry mechanismus, který automaticky řeší dočasné chyby při doručování dokumentů.

V tomto článku se dozvíte, jaké stavové kódy PSB vrací, jak interpretovat chybové odpovědi, kdy můžete bezpečně zopakovat požadavek a jak funguje automatický retry mechanismus PSB.

PSB API používá standardní HTTP stavové kódy k indikaci výsledku požadavku. Stavové kódy se dělí do dvou kategorií: chyby klienta (4xx), které musíte opravit sami, a chyby serveru (5xx), které můžete zopakovat.

Při 4xx chybě je problém v samotném požadavku. Opětovné odeslání se stejnými daty vyprodukuje stejný výsledek. Opravte příčinu před dalším pokusem.

Výjimka z pravidla „pouze 5xx lze retryovat“: 429 Too Many Requests indikuje omezování počtu požadavků a lze jej retryovat. Počkejte a respektujte hlavičku Retry-After, než požadavek znovu odesláte.

5xx chyba indikuje dočasný problém na straně serveru. Samotný požadavek může být správný. Spolu s 429 jsou to jediné stavové kódy, u kterých má opakování smysl.

Poznámka: endpoint pro odesílání akceptuje maximálně 24 MB na požadavek, včetně HTTP overheadu. Payloady překračující tento limit jsou odmítnuty webovým serverem s HTTP 500 místo 413, protože odmítnutí nastane před validací na aplikační vrstvě. Mějte to na paměti u base64-kódovaných příloh: zvětšují velikost souboru přibližně o 33 %.

Při 4xx chybě odpověď obsahuje JSON tělo popisující problém. Tyto informace vám pomohou rychle identifikovat příčinu.

{
  "error": "Validation failed",
  "message": "The supplied document is not valid UBL 2.1",
  "details": [
    "cbc:InvoiceTypeCode is missing"
  ]
}

Při 5xx chybě odpověď není vždy strukturovaná. Založte svou retry logiku na HTTP stavovém kódu, nikoli na obsahu těla.

Ne každá chyba si zaslouží retry. Pravidlo je jednoduché: pouze 5xx stavové kódy a síťové timeouty stojí za opakování. Při 4xx chybách musíte požadavek upravit před opětovným odesláním.

Doporučená strategie retryování je exponential backoff: začněte s krátkou čekací dobou a zdvojnásobte ji při každém dalším pokusu.

Tip: přidejte k čekací době malý náhodný rozptyl (jitter). Pokud po výpadku retryuje více klientů současně, jitter zabrání tomu, aby všichni zasáhli server ve stejný okamžik.

Vždy kombinujte retry logiku s hlavičkou X-EConnect-DocumentId. Zahrnutím stejného documentId při každém pokusu PSB garantuje, že dokument nebude nikdy zpracován dvakrát. Pokud PSB obdrží documentId, který již byl zpracován, vrátí 409 Conflict jako potvrzení.

Viz Idempotency: zabránění duplicitnímu odesílání pro úplné vysvětlení a příklady kódu.

Kromě retry logiky, kterou implementujete sami, má PSB vlastní retry mechanismus pro doručování dokumentů. Pokud PSB pokouší doručit fakturu nebo objednávku příjemci a ten vrátí 5xx chybu, PSB automaticky obnoví doručování.

PSB provede až 8 retry pokusů rozložených přibližně na 35 hodin. Při každém pokusu PSB publikuje událost, takže můžete sledovat průběh:

Pokud máte nakonfigurovaný webhook pro tato témata, obdržíte notifikaci při každém pokusu. Po InvoiceSentError nebo OrderSentError je vyžadována manuální akce: kontaktujte příjemce nebo eskalujte přes eConnect Support.

Tip: přihlaste se k odběru témat InvoiceSentRetry a InvoiceSentError prostřednictvím webhooku. Tímto způsobem okamžitě detekujete problémy s doručováním a můžete jednat proaktivně.

Pro webhooky PSB používá samostatný retry plán. Pokud je váš webhook endpoint nedostupný nebo nevrátí 2xx stavový kód, PSB opakuje doručení události.

PSB očekává 2xx odpověď od vašeho endpointu do 100 sekund. Jakákoliv jiná odpověď (nebo timeout) se počítá jako neúspěšný pokus. Proto zpracovávejte příchozí webhooky co nejrychleji, potvrďte příjem odpovědí 200 OK a náročné zpracování provádějte asynchronně v background procesu.

Poznámka: pokud je váš endpoint nedostupný po delší dobu, PSB přestane retryovat po 5 dnech. Zmeškané události lze stále získat prostřednictvím batch endpointu. Viz Batch hooks pro více informací.

U integrací, které přistupují k PSB z chráněné sítě (firewall, proxy, seznam povolených), musí být povoleny jak primární, tak failover názvy hostitelů. everbinding.nl je starší doména eConnect a je aktivně používána pro failover PSB.

Přidávejte všechny čtyři názvy hostitelů na whitelist na portu 443 (HTTPS). Bez názvů hostitelů failover se může platné připojení PSB během selhání strom stat nedostupné, zatímco PSB sama funguje.