Chybové kódy

Kompletný zoznam error.code hodnôt, ktoré API vracia, a kedy ich očakávať.

Field error.code v chybovej odpovedi je stabilný stringový enum, ktorý môžeš bezpečne switchovať vo svojom kóde. Texty v error.message sú human-readable a môžu sa časom zlepšovať/lokalizovať – nepoužívaj ich na kontrolu logiky.

Autentifikácia (401)

HodnotaHTTPPopis

MISSING_API_KEY401Authorization hlavička chýba alebo je prázdna.

INVALID_API_KEY401Kľúč nemá správny formát alebo neexistuje.

API_KEY_REVOKED401Kľúč bol odvolaný v UI.

API_KEY_EXPIRED401Kľúč prekročil expires_at.

Autorizácia (402 / 403)

HodnotaHTTPPopis

FORBIDDEN403Kľúču chýba scope, alebo je read_only pri write requeste.

QUOTA_REACHED402Mesačná kvóta plánu vyčerpaná (AI scans, emaily, ...).

TIER_REQUIRED403Funkcia je dostupná len na vyššom pláne.

Validácia + business pravidlá (400 / 409 / 422)

HodnotaHTTPPopis

BAD_REQUEST400Nesprávne formátovaný JSON v body.

VALIDATION_ERROR422Body neprešiel Zod validáciou (s detailom v issues).

INVALID_ID422Path parameter id má nesprávny formát.

CONFLICT409Stav nepovoľuje danú akciu (napr. mazanie sent invoice).

DUPLICATE409Unique constraint porušený (napr. duplicitný kód katalógovej položky).

Existencia entít (404)

HodnotaHTTPPopis

NOT_FOUND404Entita neexistuje alebo patrí inej organizácii.

Upload (413 / 415)

HodnotaHTTPPopis

PAYLOAD_TOO_LARGE413Upload prekročil 5 MB.

UNSUPPORTED_MEDIA_TYPE415Nepodporovaný MIME type pri uploade.

Rate limiting (429)

HodnotaHTTPPopis

RATE_LIMITED429Prekročený limit per-API-kľúč/minútu. Pozri Retry-After hlavičku.

Server-side (5xx)

HodnotaHTTPPopis

INTERNAL_SERVER_ERROR500Neočakávaná chyba na našej strane (logujeme do Sentry).

SERVICE_UNAVAILABLE503Plánovaná údržba alebo dependency outage. Retry s backoff.