Katalog błędów

Każda odpowiedź błędowa ma stabilny `code` (string) i `meta.request_id`. Kod cytuj w support tickets - szybciej znajdziemy logi.

Envelope

json

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Wyczerpano dzienny limit walidacji (1450 / 1000).",
    "details": {
      "plan": "pro",
      "period": "daily",
      "used": 1450,
      "limit": 1000
    }
  },
  "meta": {
    "request_id": "a3f9c1d8b2e7f4a1"
  }
}

request_id w nagłówku

Każda odpowiedź ma też nagłówek X-Request-Id z tą samą wartością - wygodne do logowania, gdy nie chcesz parsować body błędnej odpowiedzi.

Tabela kodów

HTTP	Code	SDK exception	Reakcja	Opis
400	`INVALID_BODY`	NaprawKsefError	Popraw payload	Body nie jest JSON-em lub brakuje wymaganego pola (np. xml).
400	`INVALID_XML`	NaprawKsefError	Popraw XML	Treść nie ma struktury KSeF - brak elementów Faktura / Naglowek.
400	`FILE_TOO_LARGE`	NaprawKsefError	Zmniejsz / podziel	XML przekracza limit 10 MB.
400	`VALIDATION_ERROR`	NaprawKsefValidationError	Popraw payload	Walidacja schematu Zod nie przeszła. Szczegóły w `details[]`.
400	`INVALID_CONTENT_TYPE`	NaprawKsefError	Ustaw header	Wymagane Content-Type: application/json lub application/xml.
400	`UNSAFE_URL`	NaprawKsefError	Użyj publicznego URL	Webhook URL wskazuje na localhost / adres prywatny (SSRF guard).
400	`UNKNOWN_EVENT`	NaprawKsefError	Sprawdź event_types	Próba subskrypcji nieznanego typu eventu webhooka.
401	`MISSING_AUTH`	NaprawKsefAuthError	Dodaj header	Brak nagłówka Authorization: Bearer ...
401	`INVALID_KEY_FORMAT`	NaprawKsefAuthError	Sprawdź klucz	Klucz nie pasuje do nk_(live\|test)_<32 hex>.
401	`INVALID_KEY`	NaprawKsefAuthError	Rotuj klucz	Klucz nieprawidłowy, wygasły, lub unieważniony.
403	`INSUFFICIENT_SCOPE`	NaprawKsefForbiddenError	Wystaw nowy klucz	Klucz nie ma wymaganego scope (np. webhooks).
404	`WEBHOOK_NOT_FOUND`	NaprawKsefNotFoundError	Sprawdź id	Webhook o podanym id nie istnieje w organizacji.
409	`IDEMPOTENCY_CONFLICT`	NaprawKsefIdempotencyConflictError	Zmień klucz	Ten Idempotency-Key został już użyty z innym body lub jest w trakcie.
422	`VALIDATION_ERROR`	NaprawKsefValidationError	Popraw payload	Pola obecne ale niepoprawne semantycznie (np. enum out of range).
429	`RATE_LIMITED`	NaprawKsefRateLimitError	Czekaj Retry-After	Wyczerpany limit minutowy/dzienny klucza.
429	`QUOTA_EXCEEDED`	NaprawKsefRateLimitError	Upgrade planu	Quota planu (dzienna/miesięczna) wyczerpana. Webhook quota.exceeded jest emitowany.
500	`VALIDATION_FAILED`	NaprawKsefServerError	Ponów / support	Wewnętrzny błąd silnika walidacji - request_id w meta.
500	`BUILD_FAILED`	NaprawKsefServerError	Ponów / support	Wewnętrzny błąd generatora korekty.
503	`DOWNSTREAM_UNAVAILABLE`	NaprawKsefServerError	Retry	Zewnętrzny system (np. baza) chwilowo niedostępny - SDK auto-retry.

Reagowanie w kodzie

typescript

import {
  NaprawKsef,
  NaprawKsefAuthError,
  NaprawKsefForbiddenError,
  NaprawKsefRateLimitError,
  NaprawKsefValidationError,
  NaprawKsefServerError,
} from "@naprawksef/sdk";

try {
  await client.validate.run({ xml });
} catch (e) {
  if (e instanceof NaprawKsefAuthError) {
    alert("Klucz API wygasł - wystaw nowy w dashboardzie.");
  } else if (e instanceof NaprawKsefValidationError) {
    showFieldErrors(e.details);
  } else if (e instanceof NaprawKsefRateLimitError) {
    enqueueWithDelay(e.retryAfterSeconds);
  } else if (e instanceof NaprawKsefServerError) {
    reportToSentry(e); // klient pewnie nie zwinie tego
  } else {
    throw e;
  }
}