Každá API integrácia skôr či neskôr narazí na chyby. Výpadok siete, nedostupný server, nesprávne formátovaný dokument: to patrí k veci. PSB API komunikuje chyby prostredníctvom štandardných HTTP stavových kódov a štruktúrovaných JSON odpovedí. Navyše PSB má zabudovaný retry mechanizmus, ktorý automaticky rieši dočasné chyby pri doručovaní dokumentov.

V tomto článku sa dozviete, aké stavové kódy PSB vracia, ako interpretovať chybové odpovede, kedy môžete bezpečne zopakovať požiadavku a ako funguje automatický retry mechanizmus PSB.

PSB API používa štandardné HTTP stavové kódy na indikáciu výsledku požiadavky. Stavové kódy sa delia do dvoch kategórií: chyby klienta (4xx), ktoré musíte opraviť sami, a chyby servera (5xx), ktoré môžete zopakovať.

Pri 4xx chybe je problém v samotnej požiadavke. Opätovné odoslanie s rovnakými dátami vyprodukuje rovnaký výsledok. Opravte príčinu pred ďalším pokusom.

Výnimka z pravidla „iba 5xx možno retryovať“: 429 Too Many Requests indikuje obmedzovanie počtu požiadaviek a možno ho retryovať. Počkajte a riaďte sa hlavičkou Retry-After, skôr než požiadavku znova odošlete.

5xx chyba indikuje dočasný problém na strane servera. Samotná požiadavka môže byť správna. Spolu s 429 sú to jediné stavové kódy, pri ktorých má opakovanie zmysel.

Poznámka: endpoint na odosielanie akceptuje maximálne 24 MB na požiadavku, vrátane HTTP overheadu. Payloady prekračujúce tento limit sú odmietnuté webovým serverom s HTTP 500 namiesto 413, pretože odmietnutie nastane pred validáciou na aplikačnej vrstve. Majte to na pamäti pri base64-kódovaných prílohách: zväčšujú veľkosť súboru približne o 33 %.

Pri 4xx chybe odpoveď obsahuje JSON telo popisujúce problém. Tieto informácie vám pomôžu rýchlo identifikovať príčinu.

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

Pri 5xx chybe odpoveď nie je vždy štruktúrovaná. Založte svoju retry logiku na HTTP stavovom kóde, nie na obsahu tela.

Nie každá chyba si zaslúži retry. Pravidlo je jednoduché: iba 5xx stavové kódy a sieťové timeouty stoja za opakovanie. Pri 4xx chybách musíte požiadavku upraviť pred opätovným odoslaním.

Odporúčaná stratégia retryovania je exponential backoff: začnite s krátkou čakacou dobou a zdvojnásobte ju pri každom ďalšom pokuse.

Tip: pridajte k čakacej dobe malý náhodný rozptyl (jitter). Ak po výpadku retryuje viacero klientov súčasne, jitter zabráni tomu, aby všetci zasiahli server v rovnakom okamihu.

Vždy kombinujte retry logiku s hlavičkou X-EConnect-DocumentId. Zahrnutím rovnakého documentId pri každom pokuse PSB garantuje, že dokument nebude nikdy spracovaný dvakrát. Ak PSB obdrží documentId, ktorý už bol spracovaný, vráti 409 Conflict ako potvrdenie.

Pozri Idempotency: zabránenie duplicitnému odosielaniu pre úplné vysvetlenie a príklady kódu.

Okrem retry logiky, ktorú implementujete sami, má PSB vlastný retry mechanizmus pre doručovanie dokumentov. Ak PSB skúša doručiť faktúru alebo objednávku príjemcovi a ten vráti 5xx chybu, PSB automaticky obnoví doručovanie.

PSB vykoná až 8 retry pokusov rozložených približne na 35 hodín. Pri každom pokuse PSB publikuje udalosť, takže môžete sledovať priebeh:

Ak máte nakonfigurovaný webhook pre tieto témy, obdržíte notifikáciu pri každom pokuse. Po InvoiceSentError alebo OrderSentError je vyžadovaná manuálna akcia: kontaktujte príjemcu alebo eskalujte cez eConnect Support.

Tip: prihláste sa na odber tém InvoiceSentRetry a InvoiceSentError prostredníctvom webhooku. Týmto spôsobom okamžite detegujete problémy s doručovaním a môžete konať proaktívne.

Pre webhooky PSB používa samostatný retry plán. Ak je váš webhook endpoint nedostupný alebo nevracia 2xx stavový kód, PSB opakuje doručenie udalosti.

PSB očakáva 2xx odpoveď od vášho endpointu do 100 sekúnd. Akákoľvek iná odpoveď (alebo timeout) sa počíta ako neúspešný pokus. Preto spracovávajte prichádzajúce webhooky čo najrýchlejšie, potvrďte príjem odpoveďou 200 OK a náročné spracovanie vykonávajte asynchrónne v background procese.

Poznámka: ak je váš endpoint nedostupný po dlhšiu dobu, PSB prestane retryovať po 5 dňoch. Zmeškané udalosti možno stále získať prostredníctvom batch endpointu. Pozri Batch hooks pre viac informácií.

Pre integrácie, ktoré pristúpujú k PSB z chránenej siete (firewall, proxy, zoznam povolených), musia byť povolené primárne aj failover názvy hostiteľov. everbinding.nl je staršia doména eConnect a aktivívne sa používa pre failover PSB.

Pridajte všetky štyri názvy hostiteľov na whitelist na porte 443 (HTTPS). Bez failover názvov hostiteľov sa môže platné pripojenie PSB počas zlyhania stať nedostupným, zatiaľ čo PSB sama beží.