> For the complete documentation index, see [llms.txt](https://docs.ecommerce.seb.ee/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/klaidu-valdymas.md).

# Klaidų valdymas

Tvarkykite SDK išimtis, diagnozuokite API klaidas ir taikykite saugias pakartotinių bandymų bei laukimo laiko politikos.

## Išimčių hierarchija

Visi SDK klaidų tipai kyla iš vienos bazės, **`ECommException`** (Java tai nekontroliuojama, `\RuntimeException` PHP kalboje, `Exception` C# kalboje, `Error` TypeScript kalboje):

| Exception                 | Išmetama, kai                                                                                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationException` | OAuth prieigos rakto gavimas nepavyksta (neteisingi prisijungimo duomenys, prieigos rakto galinis taškas nepasiekiamas arba grąžina klaidas / netinkamai suformuotus atsakymus) |
| `ConnectionException`     | Tinklo / transporto klaida: DNS, ryšys atmestas, viršytas laukimo laikas                                                                                                        |
| `SerializationException`  | Atsakymo turinio nepavyksta išanalizuoti kaip tikėtino JSON                                                                                                                     |
| `EncryptionException`     | JWE šifravimas arba rakto gavimas nepavyksta                                                                                                                                    |
| `InvalidRequestException` | (šiuo metu tik Java) kuriant užklausą trūksta privalomo lauko                                                                                                                   |
| `ApiServerException`      | Webhook klausytojui nepavyksta paleisti ar veikti                                                                                                                               |
| `EgwBootstrapException`   | Nepavyksta sukurti kliento (trūksta konfigūracijos, nerastas adapteris)                                                                                                         |
| `ECommException` (bazė)   | **API HTTP klaidų atsakymai (4xx/5xx)** — žr. toliau                                                                                                                            |

## API klaidų nuskaitymas

Kai API atmeta iškvietimą (4xx) arba įvyksta klaida (5xx), dabartinėje versijoje išmetama bazinė **`ECommException`** kurios pranešime yra operacijos pavadinimas ir HTTP būsena, pvz., `Kliento klaida vykdant initiateCitPayment: 400`.

Norėdami diagnozuoti API klaidą alfa versijoje, įjunkite SDK registravimą ir sutikrinkite pagal `X-Request-ID` antraštę — peržiūrėkite registravimo gaires [Saugumo mechanizmuose](/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/saugumo-mechanizmai.md#logging) pirma, nes klaidų turinys įrašomas nepašalinus jautrios informacijos. Žurnalas būtinas, nes struktūrizuotas klaidos turinys (`ErrorResponse` su `apiClientMessages[].code/text/category`) įrašomas per SDK registruotoją, bet nepridedamas prie išimties: negalite šakoti pagal API klaidos kodą, parodyti API pranešimo operatoriui arba kode atskirti „netinkama suma“ nuo „nežinoma parduotuvės sutartis“. Nesiimkite analizuoti išimties pranešimo; jo formatas nėra sutartinė sąsaja.

Tai yra defektas, kurį planuojama ištaisyti, o ne numatyta klaidų sutartis. Ateityje išimčių sąsaja įgis prieigos metodus, o `ECommException` bazinė klasė bus palikta, kad `catch` blokai ir toliau veiktų.

Praktinis pavyzdys (parodyta Java; kiekvienoje kalboje atitikmuo):

```java
try {
    var response = client.payments().initiateCitPayment(b -> ...);
} catch (AuthenticationException e) {
    // prisijungimo duomenų / konfigūracijos problema — nebandykite aklai kartoti; praneškite operacijų komandai
} catch (ConnectionException e) {
    // transporto problema — žr. toliau pateiktas kartojimo gaires
} catch (ECommException e) {
    // API atmetė arba nepavyko atlikti iškvietimo; pranešime nurodyta HTTP būsena
}
```

Kliento pusės tikrinimas skiriasi pagal kalbą: Java išmeta `InvalidRequestException` trūkstant privalomų laukų, statymo metu; PHP, C# ir Node.js šiuo metu netikrina kliento pusėje — ta pati klaida pasireiškia kaip `ECommException` iš serverio pusės grąžinamas 400.

## Kartojimai, idempotentiškumas, laiko limitai

SDK niekada nieko nekartoja. Kiekviena operacija vykdoma tik vieną kartą; dabartinėje versijoje nėra įdiegtos automatinio kartojimo pauzės ir nėra idempotentiškumo rakto mechanizmo. Tai turi vieną kritinę pasekmę:

> ⚠️ **Nepersiųskite būseną keičiančių iškvietimų aklai po `ConnectionException` arba viršyto laukimo laiko.** Mokėjimo inicijavimas, lėšų nurašymas, grąžinimas arba atšaukimas galėjo pasiekti serverį, nors atsakymo niekada nematėte. Atsigaukite pirmiausia užklausdami būseną — `getPaymentInformation(paymentId)` (arba atitinkamą grąžinimo / žetono funkciją) — ir siųskite pakartotinai tik jei aiškiai matyti, kad operacija neįsigaliojo. Saugiai galima kartoti tik skaitomojo pobūdžio iškvietimus (`getPaymentInformation`, `getShopDetails`, `getToken`, `getBankAccounts`).

Kiekviena užklausa turi sugeneruotą **`X-Request-ID`** antraštę (UUID). Ar šis ID grąžinamas API klaidų atsakymuose ir gali būti naudojamas susiejimui su palaikymo komanda: **\[TBC — patvirtinimas]**

Viršyto laukimo laiko politika yra **10 s prisijungimui / 30 s skaitymui, visoms kalboms** — numatytasis nustatymas, kurį taiko SDK.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.ecommerce.seb.ee/seb-docs-draft/seb-docs-public-lt/integracija/api-kliento-sdk/gaires/klaidu-valdymas.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.