> 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-et/integratsioon/api-kliendi-sdk/juhendid/vigade-kasitlemine.md).

# Vigade käsitlemine

Käsitlege SDK erandeid, diagnoosige API vigu ning rakendage turvalisi korduskatsete ja ajatõrke põhimõtteid.

## Erindite hierarhia

Kõik SDK vead pärinevad ühest baasist, **`ECommException`** (Java-s kontrollimata, `\RuntimeException` PHP-s, `Exception` C#-s, `Error` TypeScriptis):

| Exception                 | Visatakse, kui                                                                                                                     |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationException` | OAuthi märgendi hankimine ebaõnnestub (valed volitused, märgendi lõpp-punkt ei ole kättesaadav või tagastab vead/vigased vastused) |
| `ConnectionException`     | Võrgu-/edastusviga: DNS, ühendusest keelduti, ajalõpp                                                                              |
| `SerializationException`  | Vastuse keha ei ole võimalik oodatud JSON-iks parsida                                                                              |
| `EncryptionException`     | JWE krüptimine või võtme hankimine ebaõnnestub                                                                                     |
| `InvalidRequestException` | (praegu ainult Java-s) nõutud väli puudub päringu koostamisel                                                                      |
| `ApiServerException`      | Veebikonksu kuulaja ei käivitu või ei tööta                                                                                        |
| `EgwBootstrapException`   | Kliendi loomine ebaõnnestub (puuduv konfiguratsioon, adapterit ei leitud)                                                          |
| `ECommException` (baas)   | **API HTTP-veavastused (4xx/5xx)** — vt allpool                                                                                    |

## API vigade lugemine

Kui API lükkab kõne tagasi (4xx) või ebaõnnestub (5xx), viskab praegune versioon baasi **`ECommException`** mille teade sisaldab toimingu nime ja HTTP olekut, nt `Kliendipoolne viga toimingu initiateCitPayment ajal: 400`.

API vea diagnoosimiseks alfaversioonis lubage SDK logija ja seostage see `X-Request-ID` päisega — lugege esmalt logimise juhiseid [Turvamehhanismid](/seb-docs-draft/seb-docs-public-et/integratsioon/api-kliendi-sdk/juhendid/turvamehhanismid.md#logging) sest veakehad logitakse redigeerimata. Logi on vajalik, kuna struktureeritud veakeha (`ErrorResponse` koos `apiClientMessages[].code/text/category`) logitakse SDK logija kaudu, kuid ei lisata erindile: te ei saa API veakoodi põhjal harusid teha, API sõnumit operaatorile kuvada ega koodis eristada "vigane summa" ja "kaupleja leping teadmata". Ärge parsige erindi sõnumit; selle formaat ei ole leping.

See on parandamiseks planeeritud puudus, mitte kavandatud vealeping. Erindite liides saab hilisemas versioonis ligipääsumeetodid, `ECommException` samas kui `catch` plokid jätkaksid töötamist.

Praktiline muster (näidatud Java-s; igas keeles samaväärne):

```java
try {
    var response = client.payments().initiateCitPayment(b -> ...);
} catch (AuthenticationException e) {
    // volituste/konfiguratsiooni probleem — ärge proovige pimesi uuesti; teavitage operatsioone
} catch (ConnectionException e) {
    // edastusprobleem — vt allpool uuestiproovimise juhiseid
} catch (ECommException e) {
    // API lükkas kõne tagasi või see ebaõnnestus; sõnum sisaldab HTTP olekut
}
```

Kliendipoolne valideerimine erineb keele lõikes: Java viskab `InvalidRequestException` puuduvate nõutud väljade korral juba ehitamise ajal; PHP, C# ja Node.js ei valideeri praegu kliendipoolselt — sama viga avaldub `ECommException` serveripoolse 400 veana.

## Uuesti proovimised, idempotentsus, ajapiirangud

SDK ei proovi kunagi midagi uuesti. Iga toiming täidetakse täpselt üks kord; sisseehitatud tagasilööki ega idempotentsusvõtme mehhanismi praeguses versioonis ei ole. Sellel on üks kriitiline tagajärg:

> ⚠️ **Ärge saatke olekut muutvaid kõnesid pimesi uuesti pärast `ConnectionException` või ajalõppu.** Makse algatamine, kinnitamine, tagasimakse või tühistamine võib olla jõudnud serverisse ka siis, kui te vastust ei näinud. Taastage olukord, küsides esmalt olekut — `getPaymentInformation(paymentId)` (või tagasimakse/märgi vaste) — ja saatke uuesti ainult siis, kui on selgelt näha, et toiming ei mõjutanud midagi. Turvaline vabalt uuesti proovida: kirjutuskaitstud kõned (`getPaymentInformation`, `getShopDetails`, `getToken`, `getBankAccounts`).

Iga päring kannab genereeritud **`X-Request-ID`** päist (UUID). Kas see ID peegeldub API veavastustes ja on kasutatav toe poolega korrelatsiooniks: **\[täpsustamisel — kinnitus]**

Ajalõpu poliitika on **10 s ühendamiseks / 30 s lugemiseks, kõigis keeltes** — see on SDK-de vaikeseade.


---

# 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-et/integratsioon/api-kliendi-sdk/juhendid/vigade-kasitlemine.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.