> 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/integration/api-client-sdk/guides/error-handling.md).

# Error handling

Handle SDK exceptions, diagnose API errors, and apply safe retry and timeout policies.

## The exception hierarchy

All SDK errors derive from a single base, **`ECommException`** (unchecked in Java, `\RuntimeException` in PHP, `Exception` in C#, `Error` in TypeScript):

| Exception                 | Thrown when                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `AuthenticationException` | OAuth token acquisition fails (bad credentials, token endpoint unreachable or returning errors/malformed responses) |
| `ConnectionException`     | Network/transport failure: DNS, refused connection, timeout                                                         |
| `SerializationException`  | The response body cannot be parsed as the expected JSON                                                             |
| `EncryptionException`     | JWE encryption or key retrieval fails                                                                               |
| `InvalidRequestException` | (Java only, currently) a required field is missing at request construction                                          |
| `ApiServerException`      | The webhook listener fails to start or operate                                                                      |
| `EgwBootstrapException`   | Client construction fails (missing configuration, no adapter found)                                                 |
| `ECommException` (base)   | **HTTP error responses from the API (4xx/5xx)** — see below                                                         |

## Reading API errors

When the API rejects a call (4xx) or fails (5xx), the current release throws the base **`ECommException`** whose message contains the operation name and HTTP status, e.g. `Client error during initiateCitPayment: 400`.

To diagnose an API error in the alpha, enable an SDK logger and correlate on the `X-Request-ID` header — read the logging guidance in [Security mechanics](/integration/api-client-sdk/guides/security-mechanics.md#logging) first, because error bodies are logged unredacted. The log is necessary because the structured error body (`ErrorResponse` with `apiClientMessages[].code/text/category`) is logged through the SDK logger but not attached to the exception: you cannot branch on an API error code, surface the API's message to an operator, or distinguish "invalid amount" from "shop agreement unknown" in code. Do not parse the exception message; its format is not a contract.

This is a defect scheduled for fix, not the intended error contract. The exception surface will gain accessors in a later release, with `ECommException` kept as the base class so existing `catch` blocks continue to work.

Practical pattern (Java shown; equivalent in each language):

```java
try {
    var response = client.payments().initiateCitPayment(b -> ...);
} catch (AuthenticationException e) {
    // credential/config problem — do not retry blindly; alert operations
} catch (ConnectionException e) {
    // transport problem — see retry guidance below
} catch (ECommException e) {
    // API rejected or failed the call; message carries the HTTP status
}
```

Client-side validation differs by language: Java throws `InvalidRequestException` at build time for missing required fields; PHP, C# and Node.js currently do not validate client-side — the same mistake surfaces as an `ECommException` from a server-side 400.

## Retries, idempotency, timeouts

The SDK never retries anything. Every operation executes exactly once; there is no built-in backoff and no idempotency-key mechanism in the current release. This has one critical consequence:

> ⚠️ **Do not blindly re-send state-changing calls after a `ConnectionException` or timeout.** A payment initiation, capture, refund, or cancel may have reached the server even though you never saw the response. Recover by querying state first — `getPaymentInformation(paymentId)` (or the refund/token equivalent) — and only re-send if the operation demonstrably did not take effect. Safe to retry freely: read-only calls (`getPaymentInformation`, `getShopDetails`, `getToken`, `getBankAccounts`).

Every request carries a generated **`X-Request-ID`** header (UUID). Whether this ID is echoed in API error responses and usable for correlation with support: **\[TBC — confirmation]**

The timeout policy is **10 s connect / 30 s read, for every language** — the default the SDKs apply.


---

# 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/integration/api-client-sdk/guides/error-handling.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.