Error Reference

ksef2 raises SDK exceptions for failures it can classify. Transport failures raised before KSeF returns a parsed API response remain httpx.HTTPError exceptions. Presigned external-storage transfers use the dedicated exceptions described below instead of KSeF API/authentication classification.

Branch on the class or on ksef_code

Handle errors by exception class, or by ksef_code for KSeF API errors. Never branch on the message text: messages are written for people, carry the current KSeF wording and can change between releases. The same goes for hint: show it, log it, but do not parse it.

Base classes

Catch narrower subclasses before KSeFException when the workflow has a specific recovery action.

try:
    result = auth.invoices.query_metadata(filters=filters)
except KSeFRateLimitError as exc:
    retry_after = exc.retry_after
except KSeFNotReadyError:
    ...  # KSeF has not finished yet; wait and ask again
except KSeFApiError as exc:
    if exc.ksef_code == 21405:
        details = exc.details
    trace_id = exc.trace_id  # quote it when contacting KSeF support
except KSeFException as exc:
    context = exc.context
except httpx.HTTPError as exc:
    transport_error = exc

SDK exception classes

KSeFAuthTokenRedemptionError.outcome_ambiguous is always True. Do not retry the redemption: KSeF may already have consumed the temporary authentication token even though the response did not reach the caller.

External transfer attributes and batch recovery

Presigned storage responses are not KSeF API responses. A storage 403, for example, raises KSeFExternalTransferError, not KSeFAuthError. Its message and context contain only the sanitized host, operation, workflow reference, part ordinal, status code, and ambiguity flag; the signed URL is not included.

KSeFBatchUploadError.recovery_state() deliberately reveals the sensitive BatchSessionResumeState required for recovery. It is excluded from the error message and context because it contains encryption material and presigned URLs. Store it only in protected credential storage, and do not blindly retry an upload when outcome_ambiguous is True.

The original httpx failure remains available through __cause__. Avoid logging the cause indiscriminately because raw HTTP diagnostics can include the signed URL.

API error attributes

KSeFApiError is raised for parsed KSeF 4xx and 5xx responses. Specialized subclasses are used for authentication/authorization failures, rate limits and resources KSeF has not made available yet.

The same values are available in context: status_code, ksef_code, trace_id, details and hint (when there is one).

Use response.model_dump() or response.model_dump_json() for structured diagnostics when response is not None.

Message format

Every KSeF API error is formatted the same way, whatever shape the response had (application/problem+json, the older exception payload, another JSON body, text or nothing). The SDK picks the parser from the response Content-Type: application/problem+json is read as Problem Details, application/json as the older payload (except a 401, which KSeF sends as Problem Details labelled application/json), and anything else becomes a short snippet:

KSeF rejected <METHOD> <path> (HTTP <status>, KSeF code <code>): <description>
Details: <detail>; <detail>
Trace ID: <trace id>
Hint: <hint>

The KSeF code part is left out when the response has no code, and the Details, Trace ID and Hint lines appear only when there is something to show. By default the SDK sends X-Error-Format: problem-details on every request to the KSeF API (see Error format), so KSeF returns its 400 and 429 errors as application/problem+json, and trace_id is set on every API error KSeF returns in that format. (401, 403 and 410 are always Problem Details.) The header is not sent to presigned storage URLs. The response body is not part of the message; it stays on response. When the body is not a recognizable error, the description is a short, truncated snippet of it.

Error format

TransportConfig.error_format chooses the format the SDK asks KSeF for:

401, 403 and 410 are always Problem Details. The SDK reads both formats the same way, so ksef_code, details, the class and the hint do not change; only trace_id and the type of response do. Use "legacy" only if your code reads response and expects the older models:

client = Client(Environment.PRODUCTION, transport_config=TransportConfig(error_format="legacy"))

A Problem Details body that does not match its model in the KSeF spec (or comes with a status the spec has no model for, such as 500) is not parsed: the description is a snippet of the body and response is None.

For example, downloading an invoice UPO that KSeF has not issued yet (the description and details are KSeF's own words, which are Polish):

KSeF rejected GET /sessions/online/S1/invoices/I1/upo (HTTP 400, KSeF code 21178): Nie znaleziono UPO dla podanych kryteriów.
Details: UPO o numerze referencyjnym I1 nie zostało znalezione.
Trace ID: 0b1f6a7c-4d2e-4a53-9a6e-3f2b9d1c8e11
Hint: KSeF has no UPO for this yet. Call `wait()` on the invoice submission or the session first, then call `download_upo()` again. If `wait()` raises `KSeFInvoiceRejectedError`, KSeF rejected the invoice and will never issue a UPO for it.

Hints

KSeFException.hint says what to do next. It is shown on its own Hint: line in str(exc) and stored in exc.context["hint"]. A hint is set only when the SDK knows the cause, every method it names is a current one, and it can be replaced for one occurrence by passing hint=... to the exception.

Hints on API errors come from the KSeF code first, then the HTTP status. A code with its own hint keeps it on a 401 or 403 too, and the class still follows the status there (KSeFAuthError):

KSeFRateLimitError builds its hint from retry_after, for example Wait 17 seconds before retrying.

Hints on the other SDK errors:

KSeFSessionError has no class-level hint. The SDK sets one where it knows the cause: waiting on a session that is still open (close it first), and a session that KSeF finished with a failure (read the failed invoices). A rejected duplicate (440) gets its own hint on KSeFInvoiceRejectedError.

KSeF error codes

ksef_code is the number KSeF sent. The SDK never drops a code it does not know. Only 21165 and 21178 have a dedicated class (KSeFNotReadyError); the rest are plain KSeFApiError with ksef_code set (KSeFAuthError on a 401 or 403). The codes below are every code the KSeF API documentation (openapi.json) lists, all of them on HTTP 400 responses, and each has an ExceptionCode member. A unit test fails when a spec update adds a code that is not listed.

21178 does not always mean "not issued yet": KSeF also returns it, for good, for an invoice it rejected (for example a duplicate, status 440). Call wait() first; if it raises KSeFInvoiceRejectedError, there is no UPO to download.

ExceptionCode values

ExceptionCode is an IntEnum: each member's value is its KSeF code, and the names are in the table above. One more member is not a KSeF code:

Codes the enum does not list map to ExceptionCode.UNKNOWN_ERROR, but the raw number stays on ksef_code. Prefer ksef_code in new code.

Polling timeout classes

Polling timeout exceptions mean the local wait deadline expired. They do not by themselves prove the remote KSeF workflow failed.

Store the relevant reference before polling so another process can resume the status check. Every timeout error carries a hint that says how to keep waiting or resume.

download_upo() on an invoice submission, an online session and a batch session never waits and has no timeout. Call wait() on the submission or the session first. Asked too early it raises KSeFNotReadyError, with a hint that names wait(); a session that is still open raises KSeFSessionError.

Rate limit attributes

Invoice rejection attributes

KSeFInvoiceRejectedError subclasses KSeFSessionError, so existing handlers still catch it. Catch KSeFInvoiceRejectedError before KSeFSessionError when only a session-state violation should reopen or re-authenticate a session.

Unlike KSeFApiError.status_code, which is always an HTTP status, invoice_status_code comes from the KSeF invoice status object.

For a duplicate (440), extensions carries originalKsefNumber and originalSessionReferenceNumber. A caller recovering from a send whose response was lost can pass originalKsefNumber to download_invoice() and compare it against the submitted invoice. If it is the same invoice, treat the rejection as already accepted.

Related reference

• Operations reference: Review retry behavior, rate limits, workflow timeouts, and resumable state.
• Client lifecycle: Review lifecycle errors and client close behavior.
• Status and UPO: Understand status surfaces, UPO documents, and polling deadlines.