Hibakezelés

Minden hibás válasz egységes JSON borítékban érkezik, hogy a kliens kódod egyetlen helyen tudja feldolgozni a hibákat.

Hibaboríték

{
    "error": {
        "code": "VALIDATION_FAILED",
        "message": "A megadott adatok érvénytelenek.",
        "details": [
            {
                "field": "totals.0.vat_category",
                "code": "INVALID_VALUE",
                "message": "A megadott vat_category formátuma érvénytelen."
            }
        ],
        "request_id": "req_01hz3k9c8v0000000000000000"
    }
}

Mezők

Mező	Leírás
`code`	Gépileg feldolgozható hibakód (lásd lent).
`message`	Emberi olvasásra szánt hibaüzenet.
`details`	Mezőszintű validációs hibák listája (`field`, `code`, `message` hármasokkal), vagy `null`, ha nem releváns.
`request_id`	Egyedi kérés-azonosító, ugyanaz mint a válasz `X-Request-Id` fejléce — hibajelentésnél mindig ezt add meg.

Hibakódok

HTTP státusz	Kód	Jelentés
401	`UNAUTHENTICATED`	Hiányzó, érvénytelen, visszavont, lejárt API-kulcs, vagy a kulcs környezete nem egyezik a hívott aldomainnel — lásd Hitelesítés.
403	`FORBIDDEN`	A kulcs érvényes, de nincs jogosultsága a művelethez.
403	`PLAN_LIMIT_EXCEEDED`	A szervezeted csomagja szerinti keret betelt (pl. aktív adóalanyok száma vagy a havi nyugtakvóta) — válts magasabb csomagra az admin felület Előfizetés oldalán.
404	`RESOURCE_NOT_FOUND`	A hivatkozott erőforrás nem létezik ebben a szervezetben/környezetben.
422	`VALIDATION_FAILED`	A kérés törzse nem felel meg a validációs szabályoknak — lásd `details`.
422	`TAXPAYER_NOT_FOUND`	A hivatkozott `taxpayer_id` nem létezik vagy nem ehhez a szervezethez tartozik.
422	`CREDENTIALS_NOT_CONFIGURED`	Az adóalanyhoz még nincs NAV hitelesítő adat beállítva — lásd Adóalanyok.
422	`CREDENTIALS_INVALID`	A beállított NAV hitelesítő adatok érvénytelenek.
409	`RECEIPT_ALREADY_AGGREGATED`	A nyugta már bekerült egy jelentésbe, a művelet már nem hajtható végre rajta.
409	`TAXPAYER_HAS_RECEIPTS`	Az adóalany nem törölhető, mert már tartoznak hozzá nyugták vagy jelentések.
409	`REPORT_NOT_READY`	A jelentés még nincs olyan állapotban, hogy a művelet elvégezhető legyen rajta.
409	`REPORT_ALREADY_SUBMITTED`	A jelentés már be lett küldve a NAV felé.
409	`REPORT_NOT_INVALIDATABLE`	A jelentés jelenlegi állapotában nem érvényteleníthető — lásd Jelentések.
409	`IDEMPOTENCY_CONFLICT`	Ugyanazzal az `Idempotency-Key`-jel, de eltérő kérés-törzzsel érkezett a kérés — lásd Idempotencia.
429	`RATE_LIMITED`	Túl sok kérés — próbáld újra a `Retry-After` fejlécben jelzett idő után.
500	`INTERNAL_ERROR`	Váratlan szerverhiba. Ha ismétlődik, jelezd a `request_id` megadásával.

NAV- és feldolgozási hibák

A következő kódok a NAV felé történő háttér-feldolgozás során felmerülő hibákat jelölik. Ezek nem egy konkrét API-hívás válaszában jelennek meg, hanem a kapcsolódó jelentés vagy beküldés status/hibamezőin, illetve webhook eseményeken keresztül kérdezhetők le:

Kód	Jelentés
`NAV_AUTHENTICATION_FAILED`	A NAV elutasította a technikai felhasználó hitelesítését.
`NAV_SCHEMA_VALIDATION_FAILED`	A NAV felé küldött XML nem felel meg a NAV séma-elvárásainak.
`NAV_SUBMISSION_REJECTED`	A NAV üzleti szabály alapján elutasította az adatszolgáltatást.
`UPSTREAM_UNAVAILABLE`	A NAV rendszere átmenetileg nem elérhető.
`UPSTREAM_TIMEOUT`	A NAV rendszere nem válaszolt időben.
`UPSTREAM_INVALID_RESPONSE`	A NAV rendszere értelmezhetetlen választ adott.