Skip to content

errors.md

Latest commit

 

History

History
136 lines (105 loc) · 5.17 KB

errors.md

File metadata and controls

136 lines (105 loc) · 5.17 KB
Raw

Błędy, rate limits i retry

SDK mapuje błędy HTTP i błędy walidacji na dedykowane klasy wyjątków.

Typy błędów

Klasa Kiedy występuje Najważniejsze pola
KsefError Bazowy błąd SDK (np. błędy workflow). message
KsefHttpError Odpowiedź HTTP >= 400 bez JSON. statusCode, responseBody, problem?
KsefApiError Odpowiedź HTTP >= 400 z JSON. statusCode, responseBody, problem?
KsefRateLimitError 429 Too Many Requests. statusCode, responseBody, retryAfter, retryAfterSeconds, problem?
KsefAuthStatusError Specjalny przypadek 460 (status auth wskazujący m.in. zawieszony certyfikat). statusCode, responseBody, statusDetails
KsefSessionExpiredError Brak tokena dostępowego lub nieudane odświeżenie sesji. message
KsefValidationError Błąd lokalnej walidacji danych wejściowych. message, details

problem i KSeF API 2.4.0

Przy odpowiedziach JSON SDK próbuje zmapować error.problem do jednego z modeli:

  • BadRequestProblemDetails dla 400 application/problem+json
  • UnauthorizedProblemDetails dla 401 application/problem+json
  • ForbiddenProblemDetails dla 403 application/problem+json
  • GoneProblemDetails dla 410 application/problem+json
  • TooManyRequestsProblemDetails albo legacy TooManyRequestsResponse dla 429
  • ExceptionResponse dla klasycznego formatu błędu KSeF
  • fallback UnknownApiProblem, gdy JSON nie pasuje do znanego modelu

Mapowanie do konkretnego typed modelu następuje tylko wtedy, gdy payload spełnia wymagane pola kontraktu ksef-docs 2.4.0. Przy częściowym albo niepoprawnym problem+json SDK zachowuje responseBody, a error.problem przechodzi do UnknownApiProblem.

410 Gone może pojawić się po wygaśnięciu retencji technicznych statusów operacji asynchronicznych np. dla GET /auth/{referenceNumber} albo GET /invoices/exports/{referenceNumber}.

Bogatszy format application/problem+json dla 400 i 429 jest opcjonalny i można go włączyć przez globalny nagłówek klienta:

const client = new KsefClient({
  environment: "DEMO",
  headers: {
    "X-Error-Format": "problem-details",
  },
});

Przykład obsługi 429 i Retry-After

import { KsefRateLimitError } from "ksef-client-typescript";

try {
  await client.invoices.queryInvoiceMetadata({ subjectType: "Subject1" });
} catch (error) {
  if (error instanceof KsefRateLimitError) {
    console.error("Przekroczono limit. Retry-After:", error.retryAfter);
    console.error("Retry-After (sekundy):", error.retryAfterSeconds);
  }
  throw error;
}

Przykład obsługi problem+json

import { KsefApiError } from "ksef-client-typescript";

try {
  await client.invoices.queryInvoiceMetadata({ subjectType: "Subject1" });
} catch (error) {
  if (error instanceof KsefApiError && error.problem) {
    console.error(error.problem.title, error.problem.detail);
  }
  throw error;
}

Przykład obsługi 460 (status auth)

import { KsefAuthStatusError } from "ksef-client-typescript";

try {
  await client.workflows.auth.authenticateWithXadesSignature({
    signedXml: "<AuthTokenRequest>...signed...</AuthTokenRequest>",
  });
} catch (error) {
  if (error instanceof KsefAuthStatusError && error.statusCode === 460) {
    console.error("Uwierzytelnianie odrzucone:", error.statusDetails);
  }
  throw error;
}

Przykład obsługi wygaśnięcia sesji

import { KsefSessionExpiredError } from "ksef-client-typescript";

try {
  await client.invoices.queryInvoiceMetadata({
    subjectType: "Subject1",
    dateRange: { dateType: "Issue", from: "2025-01-01", to: "2025-01-31" },
  });
} catch (error) {
  if (error instanceof KsefSessionExpiredError) {
    console.error("Sesja wygasła. Wymagane ponowne uwierzytelnienie.");
  }
  throw error;
}

Automatyczny retry na 429

Domyślnie biblioteka ponawia żądania tylko dla metod idempotentnych:

  • GET
  • PUT
  • DELETE

Mechanizm retry:

  • respektuje nagłówek Retry-After (sekundy lub data HTTP),
  • gdy nagłówek nie występuje, stosuje opóźnienie wykładnicze z jitterem,
  • ogranicza opóźnienie przez maxRetryDelayMs.

Konfiguracja globalna znajduje się w KsefClientOptions:

  • retryOn429
  • maxRetryAttempts
  • maxRetryDelayMs

Błędy workflow uwierzytelniania

AuthCoordinator może zgłosić KsefError, jeżeli status uwierzytelniania zakończy się kodem innym niż oczekiwany (100 w trakcie lub 200 po sukcesie), albo gdy przekroczony zostanie limit prób odpytywania.