Přeskočit obsah

Chybové kódy

ScriptorMed používá strukturovaný systém chybových kódů ve formátu SM-{DOMÉNA}-{NNN}. Každý kód jednoznačně identifikuje typ chyby, oblast systému, kde k ní došlo, a to, zda je zobrazena lékaři nebo sledována pouze interně.


Formát kódu

SM-UPLOAD-005
│  │       └── pořadové číslo (třímístné)
│  └────────── doména (oblast systému)
└──────────── prefix ScriptorMed

Kódy jsou trvalé — jednou přidělený kód není nikdy znovu použit. Zrušený kód zůstane reserved.


Domény

Doména Oblast systému Viditelnost
UPLOAD Upload a validace souboru uživatel
PREP Audio preprocessing uživatel
STT Speech-to-Text přepis uživatel
LLM Generování klinické zprávy uživatel
S3 Úložiště (MinIO) uživatel
PIPE Obecný pipeline uživatel
SAVE Uložení výsledku uživatel
LIC Licencování uživatel
MACRO Makra doporučení dle diagnózy uživatel
DEMO Ukázková zpráva uživatel
UHRADY Modul Plenia — zpracování K-dávek uživatel
AUTH Autentizace interní
EMAIL Doručování e-mailů interní
PAY Platby interní
BILL Fakturace interní
ADMIN Admin operace interní
INFRA Infrastruktura interní

Viditelnost

Uživatelské kódy (domény UPLOAD – LIC)

Lékaři tyto kódy vidí přímo v Desktop aplikaci — v dialogu chyby po neúspěšném zpracování konzultace.

Ukázka zobrazení v Desktop aplikaci

Zpracování selhalo
──────────────────
Překročen limit konzultací.
Kód chyby: SM-UPLOAD-005

Kontaktujte podporu nebo si zakupte doplněk konzultací.

Kód spolu se zprávou lze nahlásit podpoře, která tak okamžitě identifikuje příčinu problému.

Interní kódy (domény AUTH – INFRA)

Tyto kódy se lékaři nezobrazují. Jsou dostupné výhradně v:

  • Admin panelu — v detailu každé chyby v sekci Logy & chyby
  • Sentry — v telemetrii jako tag error_code

Přehled kódů

UPLOAD — Upload a validace

Chyby zachycené při příjmu nahrávky z Desktop aplikace.

Kód Zpráva Znovu odeslat? HTTP
SM-UPLOAD-001 Neplatný WAV soubor. Ne 400
SM-UPLOAD-002 Neplatné audio parametry. Ne 400
SM-UPLOAD-003 Chyba při sloučení audio souborů. Ne 400
SM-UPLOAD-004 Chyba čtení nahraného souboru. Ano 500
SM-UPLOAD-005 Překročen limit konzultací. Ne 429
SM-UPLOAD-006 Selhalo nahrání do úložiště. Ano 503
SM-UPLOAD-007 Chyba uložení do databáze. Ano 503
SM-UPLOAD-008 Chyba odeslání do fronty zpracování. Ano 503

PREP — Audio preprocessing

Chyby při přípravě a normalizaci audia před přepisem.

Kód Zpráva Znovu odeslat?
SM-PREP-001 Chyba načtení konfigurace preprocessoru. Ano
SM-PREP-002 Neplatná vzorkovací frekvence. Ne
SM-PREP-003 Chyba analýzy hlasitosti. Ano
SM-PREP-004 Chyba zpracování audia. Ano
SM-PREP-005 Preprocessing selhalo. Ano
SM-PREP-006 Nepodporovaný formát audia. Ne
SM-PREP-007 Dekódování OGG/Opus audia selhalo. Ne

STT — Speech-to-Text

Chyby přepisu řeči na text.

Kód Zpráva Znovu odeslat?
SM-STT-001 Chyba čtení délky WAV. Ne
SM-STT-002 Chyba inicializace STT providera. Ano
SM-STT-003 Síťová chyba při přepisu řeči. Ano
SM-STT-004 Timeout při přepisu řeči. Ano
SM-STT-005 Azure STT cancel/error. Ano
SM-STT-006 Chybí API klíč pro STT. Ne
SM-STT-007 Neplatná HTTP odpověď z STT API. Ano
SM-STT-008 Kvóta STT providera vyčerpána. Ne
SM-STT-009 Přepis řeči selhal (všechny providery). Ne

LLM — Generování zprávy

Chyby při generování klinického záznamu jazykovým modelem.

Kód Zpráva Znovu odeslat?
SM-LLM-001 API chyba LLM providera. Ano
SM-LLM-002 Prázdná odpověď z LLM. Ano
SM-LLM-003 Chyba parsování odpovědi LLM. Ano
SM-LLM-004 Generování klinického záznamu selhalo. Ano
SM-LLM-005 Chyba šablony pro LLM. Ne
SM-LLM-006 Kvóta LLM providera vyčerpána. Ne
SM-LLM-007 Generování selhalo (všechny providery). Ne

S3 — Úložiště

Chyby práce se soubory v objektovém úložišti (MinIO).

Kód Zpráva Znovu odeslat?
SM-S3-001 Chyba inicializace úložiště. Ne
SM-S3-002 Bucket neexistuje. Ano
SM-S3-003 Nahrání souboru do úložiště selhalo. Ano
SM-S3-004 Stažení souboru z úložiště selhalo. Ano
SM-S3-005 Soubor nenalezen v úložišti. Ne
SM-S3-006 Smazání souboru z úložiště selhalo. Ano
SM-S3-007 Generování URL pro stažení selhalo. Ano

PIPE — Obecný pipeline

Chyby na úrovni orchestrace celého zpracovacího řetězce.

Kód Zpráva Znovu odeslat?
SM-PIPE-001 Neočekávaná chyba v pipeline. Ano
SM-PIPE-002 Maximální počet pokusů vyčerpán. Ne
SM-PIPE-003 Chyba při úklidu. Ano

SAVE — Uložení výsledku

Chyby při finálním uložení zprávy a usage záznamu.

Kód Zpráva Znovu odeslat?
SM-SAVE-001 Chyba načtení šablony. Ano
SM-SAVE-002 Chyba výpočtu nákladů. Ne
SM-SAVE-003 Chyba zápisu usage logu. Ne
SM-SAVE-004 Chyba finálního uložení. Ano

LIC — Licencování

Chyby související s licenčním klíčem, zařízením a limity účtu.

Kód Zpráva Znovu odeslat? HTTP
SM-LIC-001 Neplatný licenční klíč. Ne 403
SM-LIC-002 Licence pozastavena. Ne 403
SM-LIC-003 Licence zrušena. Ne 403
SM-LIC-004 Platnost trial verze vypršela. Ne 403
SM-LIC-005 Účet neaktivní. Ne 403
SM-LIC-006 Účet zrušen. Ne 403
SM-LIC-007 Zařízení zablokováno. Ne 403
SM-LIC-008 Všechna zařízení obsazena. Ne 403
SM-LIC-009 Konzultace vyčerpány. Ne 429
SM-LIC-010 Překročen limit uvolnění zařízení. Ne 429
SM-LIC-011 Překročen denní limit zasílání klíče. Ne 429

MACRO — Makra doporučení dle diagnózy

Chyby při správě a importu maker v Nastavení → Doporučení dle diagnózy.

Kód Zpráva Znovu odeslat? HTTP
SM-MACRO-001 Dosažen limit počtu maker (max 30 na ordinaci). Ne 400
SM-MACRO-002 Název, kód nebo klíčové slovo makra obsahuje nepovolený text. Ne 422
SM-MACRO-003 Denní limit pro import maker byl vyčerpán (max 3× za den). Zkuste to zítra. Ano 429
SM-MACRO-004 Ve vloženém textu se nepodařilo rozpoznat žádné makro. Ne 422
SM-MACRO-005 Rozpoznání maker selhalo — zkuste to znovu. Ano 502

DEMO — Ukázková zpráva

Chyby při generování ukázkové zprávy.

Kód Zpráva Znovu odeslat? HTTP
SM-DEMO-001 Limit ukázkových zpráv byl vyčerpán. Ne 429
SM-DEMO-002 Ukázka pro vaši odbornost zatím není k dispozici. Ne 503

UHRADY — Modul Plenia

Chyby při zpracování nahrané K-dávky v modulu Plenia.

Kód Zpráva Znovu odeslat?
SM-UHR-PARSE-001 K-dávku se nepodařilo zpracovat (neplatný formát souboru). Ne

Interní kódy

Následující domény jsou viditelné pouze v admin panelu a Sentry. Lékaři tyto kódy nikdy nevidí.

AUTH — Autentizace

Kód Zpráva Znovu odeslat? HTTP
SM-AUTH-001 Neplatný přihlašovací token. Ne 401
SM-AUTH-002 Neplatné přihlašovací údaje. Ne 401
SM-AUTH-003 Účet je deaktivován. Ne 403
SM-AUTH-004 Email není ověřen. Ne 403
SM-AUTH-005 Překročen limit zařízení. Ne 403
SM-AUTH-006 API klíč expiroval. Ne 401
SM-AUTH-007 Neplatný refresh token. Ne 401

EMAIL — Doručování e-mailů

Kód Zpráva Znovu odeslat?
SM-EMAIL-001 Odeslání emailu selhalo. Ano
SM-EMAIL-002 Redis fronta pro retry nedostupná. Ne
SM-EMAIL-003 Poškozená zpráva v retry frontě. Ne
SM-EMAIL-004 Email přesunut do dead queue. Ne
SM-EMAIL-005 Chyba načtení email šablony. Ne
SM-EMAIL-006 Retry email task selhala. Ano

PAY — Platby

Kód Zpráva Znovu odeslat?
SM-PAY-001 Stripe API chyba. Ano
SM-PAY-002 Neplatný webhook podpis. Ne
SM-PAY-003 Webhook handler chyba. Ano
SM-PAY-004 Fio API chyba. Ano
SM-PAY-005 Fio JSON parse chyba. Ano

BILL — Fakturace

Kód Zpráva Znovu odeslat?
SM-BILL-001 Trial plán nenalezen. Ne
SM-BILL-002 Chyba generování čísla faktury. Ne
SM-BILL-003 Chyba generování PDF faktury. Ano
SM-BILL-004 Neznámý variabilní symbol. Ne
SM-BILL-005 Nesedí částka platby. Ne
SM-BILL-006 Dunning process chyba. Ano

INFRA — Infrastruktura

Kód Zpráva Znovu odeslat?
SM-INFRA-001 Redis nedostupný. Ano
SM-INFRA-002 Redis init fail. Ne
SM-INFRA-003 DB commit selhání. Ano

Hlášky licence a zkušebního období

Kromě chybových kódů zobrazuje Desktop aplikace tyto hlášky (nejsou to chyby zpracování — týkají se licence a trialu):

Hláška Kdy se zobrazí Co dělat
„Trial končí, poslední den." Poslední den zkušebního období a během ochranné lhůty Vyberte si plán na portálu — vše nahrané zůstává
„Trial vypršel — pro pokračování upgradujte." Po konci trialu vč. ochranné lhůty, při pokusu začít novou nahrávku Novou nahrávku nelze začít; rozpracovaná práce a odeslání běží dál. Upgradujte na portálu
„Zkušební období vypršelo. Pro pokračování kontaktujte ScriptorMed." (banner) + „Trial vypršel" (stavový řádek) Po vypršení trialu Upgrade na portálu nebo kontakt
„Problém s licenčním klíčem. Nahrávání funguje, odesílání se obnoví po opravě klíče v Nastavení." Neplatný/zrušený klíč nebo klíč vázaný na jiné zařízení Nahrávání není blokováno. Opravte klíč v Nastavení — čekající nahrávky se pak odešlou samy

Rozdíl mezi vypršeným trialem a chybným klíčem: trial blokuje začátek nové nahrávky, chybný klíč nahrávání neblokuje (jen pozastaví odesílání do opravy).


Co dělat při chybě

Pokud Desktop aplikace zobrazí chybový kód, poznamenejte si ho a kontaktujte podporu:

Kód nám umožní okamžitě identifikovat příčinu a navrhnout řešení. Pokud je u kódu uvedeno „Znovu odeslat: Ano", lze konzultaci zkusit zpracovat znovu — přejděte do seznamu konzultací a vyberte možnost Zpracovat znovu.

Pokud aplikace hlásí chybějící audio soubor (např. po neočekávaném vypnutí počítače), použijte opravu dat: Nastavení → Podpora → Opravit data — aplikace porovná stav se serverem a zaseknuté konzultace obnoví.

V admin panelu jsou kódy zobrazeny v detailu každé chyby. Použijte kód jako filtr nebo vyhledejte incident v Sentry pomocí tagu error_code.

Autoritativní seznam všech kódů a jejich definic je v souboru app/core/errors.py (třída Errors) v backendu.