Hibakezelés, hibakódok

Ha egy Számla Agent kérés nem sikerül, az ok szinte mindig a kérés adataiban vagy a fiók beállításaiban van. Ugyanazt a kérést újra elküldeni ilyenkor nem segít, sőt, a Számlázz.hu ki is tilthatja a fiókot. Ezért a kassza minden hibát egyetlen típusba, a SzamlazzError-ba gyűjt, és megmondja, milyen kategóriába esik, és mit érdemes tenni.

A SzamlazzError#

Minden kassza metódus SzamlazzError-t dob. A isSzamlazzError() típusőrrel biztonságosan szűkítheted a catch ágban kapott értéket:

import { isSzamlazzError } from 'kassza'

try {
  await kassza.invoices.create(szamla)
} catch (error) {
  if (!isSzamlazzError(error)) throw error

  switch (error.category) {
    case 'validation':
      return { hiba: error.message, tipp: error.hint }
    case 'auth':
    case 'account':
      riasztas(`Számlázz.hu fiókhiba: ${error.message}`)
      throw error
    default:
      throw error
  }
}

Mező	Típus	Leírás
`message`	`string`	Magyar hibaüzenet. A Számlázz.hu kódját `[57]` alakban az elejére teszi.
`code`	`number \| undefined`	A Számlázz.hu hibakódja. Kliensoldali hibánál nincs.
`category`	`SzamlazzErrorCategory`	A hiba kategóriája, lásd lent.
`retryable`	`boolean`	`true` karbantartásnál, hálózati hibánál és időtúllépésnél.
`hint`	`string \| undefined`	Magyar javítási tipp, ha ismert.
`action`	`AgentAction \| undefined`	A művelet, például `createInvoice`.
`httpStatus`	`number \| undefined`	A válasz HTTP státusza.
`rawResponse`	`string \| undefined`	A nyers válasz első 2000 karaktere. PDF-nél nincs.
`isDuplicate`, `isNotFound`	`boolean`	Rövidítés a `duplicate` és a `not_found` kategóriára.
`docsUrl`	`string \| undefined`	A hibakód saját oldala a hibakódok között, ha a kód ismert.

Amit a kassza újrapróbál#

A kassza csak ott próbálkozik újra, ahol ez nem okozhat dupla bizonylatot: lekérdezéseknél, a befizetések felülírásánál, és a callId-val védett nyugtáknál. Csak a retryable hibáknál teszi ezt (maintenance, network, timeout), alapból háromszor, 1, majd 2 másodperc várakozással. A számlakészítést soha nem küldi újra.

kassza metódus	Agent form mező	Automatikus újrapróbálás
`invoices.create(), invoices.preview()`	`action-xmlagentxmlfile`	soha
`invoices.reverse()`	`action-szamla_agent_st`	soha
`invoices.registerPayment(), invoices.clearPayments()`	`action-szamla_agent_kifiz`	csak felülíró (additive: false) hívásnál
`invoices.getPdf(), verifyCredentials()`	`action-szamla_agent_pdf`	igen
`invoices.get(), invoices.find()`	`action-szamla_agent_xml`	igen
`invoices.deleteProforma()`	`action-szamla_agent_dijbekero_torlese`	soha
`receipts.create()`	`action-szamla_agent_nyugta_create`	csak callId megadásával
`receipts.reverse()`	`action-szamla_agent_nyugta_storno`	csak callId megadásával
`receipts.get(), receipts.find()`	`action-szamla_agent_nyugta_get`	igen
`receipts.send()`	`action-szamla_agent_nyugta_send`	soha
`taxpayer.query()`	`action-szamla_agent_taxpayer`	igen
`connectPrincipal() (kassza/delegation)`	`action-agent_ceg_mb`	soha

A próbálkozások számát a maxAttempts, a várakozást a retryDelayMs opcióval állíthatod. A maxAttempts értéke 5 fölé nem mehet, mert a Számlázz.hu ennyit enged egy kérésre.

Bizonytalan kimenet: számla készült vagy nem?#

Hálózati hiba vagy időtúllépés után nem tudhatod, hogy a Számlázz.hu megkapta-e a kérést. Az 56-os hibánál (partial_success) a számla biztosan elkészült, csak az értesítő e-mail nem ment ki. A 71-es és 152-es hibánál (duplicate) a rendelésszámmal már készült számla.

Mindegyik esetben ugyanaz a helyes lépés: kérdezd le a számlát a rendelésszám alapján, mielőtt újra kiállítanád. Ehhez minden számlánál adj meg orderNumber-t.

import { type CreateInvoiceInput, isSzamlazzError } from 'kassza'

const BIZONYTALAN = ['network', 'timeout', 'partial_success', 'duplicate']

async function szamlaz(orderNumber: string, adatok: CreateInvoiceInput) {
  const meglevo = await kassza.invoices.find({ orderNumber })
  if (meglevo) return meglevo.header.number

  try {
    const szamla = await kassza.invoices.create({ ...adatok, orderNumber })
    return szamla.number
  } catch (error) {
    if (isSzamlazzError(error) && BIZONYTALAN.includes(error.category)) {
      const letrejott = await kassza.invoices.find({ orderNumber })
      if (letrejott) return letrejott.header.number
    }
    throw error
  }
}

Idempotens számlázás hiba után

Részleges siker (56) után a find megtalálja a számlát, dupla számla nem készül.

Futtatás a sandboxban

hibakezeles-idempotens.ts

import { ,  } from 'kassza'
import {  } from 'kassza-sandbox'

const  = ()

interface Rendeles {
  readonly : number
  readonly : string
  readonly : string
  readonly : number
}

async function (: Rendeles): <string> {
  const  = `REND-${.}`

  const  = await ..({  })
  if () return `${..} (már létezett)`

  try {
    const  = await ..({
      ,
      : true,
      : 'bankkártya',
      : {
        : .,
        : '1111',
        : 'Budapest',
        : 'Fő utca 1.',
        : .,
      },
      : [{ : 'Rendelés', : ., : 27 }],
    })
    return `${.} (új)`
  } catch () {
    const  = ['network', 'timeout', 'partial_success', 'duplicate']
    if (() && .(.)) {
      const  = await ..({  })
      if () return `${..} (a hiba ellenére elkészült)`
    }
    throw 
  }
}

const : Rendeles = {
  : 5001,
  : 'Nagy Péter',
  : 'peter@example.hu',
  : 12_700,
}

.failNext('createInvoice', 56)
await ()
await ()

1. Számla adatai · action-szamla_agent_xml

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlaxml xmlns="http://www.szamlazz.hu/xmlszamlaxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlaxml https://www.szamlazz.hu/szamla/docs/xsds/agentxml/xmlszamlaxml.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <rendelesSzam>REND-5001</rendelesSzam>
</xmlszamlaxml>

2. Számla létrehozás · action-xmlagentxmlfile

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamla xmlns="http://www.szamlazz.hu/xmlszamla" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamla https://www.szamlazz.hu/szamla/docs/xsds/agent/xmlszamla.xsd">
  <beallitasok>
    <szamlaagentkulcs>••••••••</szamlaagentkulcs>
    <eszamla>false</eszamla>
    <szamlaLetoltes>true</szamlaLetoltes>
    <valaszVerzio>2</valaszVerzio>
    <aggregator>3UMUqqWEJ7bXfJp9KXNWcrddY9sKjDVD</aggregator>
  </beallitasok>
  <fejlec>
    <keltDatum>2026-11-05</keltDatum>
    <teljesitesDatum>2026-11-05</teljesitesDatum>
    <fizetesiHataridoDatum>2026-11-05</fizetesiHataridoDatum>
    <fizmod>bankkártya</fizmod>
    <penznem>HUF</penznem>
    <szamlaNyelve>hu</szamlaNyelve>
    <rendelesSzam>REND-5001</rendelesSzam>
    <fizetve>true</fizetve>
  </fejlec>
  <elado></elado>
  <vevo>
    <nev>Nagy Péter</nev>
    <irsz>1111</irsz>
    <telepules>Budapest</telepules>
    <cim>Fő utca 1.</cim>
    <email>peter@example.hu</email>
    <sendEmail>true</sendEmail>
  </vevo>
  <tetelek>
    <tetel>
      <megnevezes>Rendelés</megnevezes>
      <mennyiseg>1</mennyiseg>
      <mennyisegiEgyseg>db</mennyisegiEgyseg>
      <nettoEgysegar>10000</nettoEgysegar>
      <afakulcs>27</afakulcs>
      <nettoErtek>10000</nettoErtek>
      <afaErtek>2700</afaErtek>
      <bruttoErtek>12700</bruttoErtek>
    </tetel>
  </tetelek>
</xmlszamla>

3. Számla adatai · action-szamla_agent_xml

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlaxml xmlns="http://www.szamlazz.hu/xmlszamlaxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlaxml https://www.szamlazz.hu/szamla/docs/xsds/agentxml/xmlszamlaxml.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <rendelesSzam>REND-5001</rendelesSzam>
</xmlszamlaxml>

4. Számla adatai · action-szamla_agent_xml

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlaxml xmlns="http://www.szamlazz.hu/xmlszamlaxml" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamlaxml https://www.szamlazz.hu/szamla/docs/xsds/agentxml/xmlszamlaxml.xsd">
  <szamlaagentkulcs>••••••••</szamlaagentkulcs>
  <rendelesSzam>REND-5001</rendelesSzam>
</xmlszamlaxml>

1. Számla adatai · válasz, HTTP 200

content-type: text/plain; charset=UTF-8
szlahu_error: Hi%C3%A1nyz%C3%B3%20adat%3A%20ismeretlen%20sz%C3%A1mlasz%C3%A1m%2C%20rendel%C3%A9ssz%C3%A1m%20vagy%20k%C3%BCls%C5%91%20azonos%C3%ADt%C3%B3.
szlahu_error_code: 7
set-cookie: JSESSIONID=ABE917083896F9EAFE28BEAC; Path=/szamla; Secure; HttpOnly

[ERR] [7] Hiányzó adat: ismeretlen számlaszám, rendelésszám vagy külső azonosító.

2. Számla létrehozás · válasz, HTTP 200

content-type: application/xml; charset=UTF-8
szlahu_error: A%20bizonylat%20elk%C3%A9sz%C3%BClt%2C%20de%20az%20%C3%A9rtes%C3%ADt%C5%91%20e-mail%20kik%C3%BCld%C3%A9se%20sikertelen.
szlahu_error_code: 56

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlavalasz xmlns="http://www.szamlazz.hu/xmlszamlavalasz">
  <sikeres>false</sikeres>
  <hibakod>56</hibakod>
  <hibauzenet>A bizonylat elkészült, de az értesítő e-mail kiküldése sikertelen.</hibauzenet>
</xmlszamlavalasz>

3. Számla adatai · válasz, HTTP 200

content-type: application/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<szamla xmlns="http://www.szamlazz.hu/szamla">
  <szallito>
    <id>1</id>
    <nev>Minta Webáruház Kft.</nev>
    <cim>
      <orszag>Magyarország</orszag>
      <irsz>1111</irsz>
      <telepules>Budapest</telepules>
      <cim>Minta utca 12.</cim>
    </cim>
    <adoszam>23456787-2-13</adoszam>
    <bank>
      <nev>Minta Bank Zrt.</nev>
      <bankszamla>11773016-11111018</bankszamla>
    </bank>
  </szallito>
  <alap>
    <id>1001</id>
    <szamlaszam>KASSZA-2026-1</szamlaszam>
    <forras>1</forras>
    <tipus>SZ</tipus>
    <eszamla>0</eszamla>
    <kelt>2026-11-05</kelt>
    <telj>2026-11-05</telj>
    <fizh>2026-11-05</fizh>
    <fizmod>bankkártya</fizmod>
    <keszpenz>false</keszpenz>
    <rendelesszam>REND-5001</rendelesszam>
    <nyelv>hu</nyelv>
    <devizanem>HUF</devizanem>
    <penzforg>false</penzforg>
    <kata>false</kata>
    <email>peter@example.hu</email>
    <teszt>true</teszt>
    <sztornozott>false</sztornozott>
  </alap>
  <vevo>
    <id>51001</id>
    <nev>Nagy Péter</nev>
    <cim>
      <orszag>Magyarország</orszag>
      <irsz>1111</irsz>
      <telepules>Budapest</telepules>
      <cim>Fő utca 1.</cim>
    </cim>
    <email>peter@example.hu</email>
  </vevo>
  <tetelek>
    <tetel>
      <nev>Rendelés</nev>
      <mennyiseg>1</mennyiseg>
      <mennyisegiegyseg>db</mennyisegiegyseg>
      <nettoegysegar>10000</nettoegysegar>
      <afakulcs>27</afakulcs>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
      <sztetordering>1</sztetordering>
    </tetel>
  </tetelek>
  <osszegek>
    <afakulcsossz>
      <afakulcs>27</afakulcs>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
    </afakulcsossz>
    <totalossz>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
    </totalossz>
  </osszegek>
  <kifizetesek>
    <kifizetes>
      <datum>2026-11-05</datum>
      <jogcim>bankkártya</jogcim>
      <osszeg>12700</osszeg>
    </kifizetes>
  </kifizetesek>
</szamla>

4. Számla adatai · válasz, HTTP 200

content-type: application/xml; charset=UTF-8

<?xml version="1.0" encoding="UTF-8"?>
<szamla xmlns="http://www.szamlazz.hu/szamla">
  <szallito>
    <id>1</id>
    <nev>Minta Webáruház Kft.</nev>
    <cim>
      <orszag>Magyarország</orszag>
      <irsz>1111</irsz>
      <telepules>Budapest</telepules>
      <cim>Minta utca 12.</cim>
    </cim>
    <adoszam>23456787-2-13</adoszam>
    <bank>
      <nev>Minta Bank Zrt.</nev>
      <bankszamla>11773016-11111018</bankszamla>
    </bank>
  </szallito>
  <alap>
    <id>1001</id>
    <szamlaszam>KASSZA-2026-1</szamlaszam>
    <forras>1</forras>
    <tipus>SZ</tipus>
    <eszamla>0</eszamla>
    <kelt>2026-11-05</kelt>
    <telj>2026-11-05</telj>
    <fizh>2026-11-05</fizh>
    <fizmod>bankkártya</fizmod>
    <keszpenz>false</keszpenz>
    <rendelesszam>REND-5001</rendelesszam>
    <nyelv>hu</nyelv>
    <devizanem>HUF</devizanem>
    <penzforg>false</penzforg>
    <kata>false</kata>
    <email>peter@example.hu</email>
    <teszt>true</teszt>
    <sztornozott>false</sztornozott>
  </alap>
  <vevo>
    <id>51001</id>
    <nev>Nagy Péter</nev>
    <cim>
      <orszag>Magyarország</orszag>
      <irsz>1111</irsz>
      <telepules>Budapest</telepules>
      <cim>Fő utca 1.</cim>
    </cim>
    <email>peter@example.hu</email>
  </vevo>
  <tetelek>
    <tetel>
      <nev>Rendelés</nev>
      <mennyiseg>1</mennyiseg>
      <mennyisegiegyseg>db</mennyisegiegyseg>
      <nettoegysegar>10000</nettoegysegar>
      <afakulcs>27</afakulcs>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
      <sztetordering>1</sztetordering>
    </tetel>
  </tetelek>
  <osszegek>
    <afakulcsossz>
      <afakulcs>27</afakulcs>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
    </afakulcsossz>
    <totalossz>
      <netto>10000</netto>
      <afa>2700</afa>
      <brutto>12700</brutto>
    </totalossz>
  </osszegek>
  <kifizetesek>
    <kifizetes>
      <datum>2026-11-05</datum>
      <jogcim>bankkártya</jogcim>
      <osszeg>12700</osszeg>
    </kifizetes>
  </kifizetesek>
</szamla>

Ezt a lépéssort a kassza el is végzi helyetted: az invoices.createOnce() és a receipts.createOnce() kiállítás előtt megkeresi a bizonylatot, bizonytalan kimenet után pedig újra megkeresi, mielőtt hibát adna. A részletek a Pontosan egyszer oldalon vannak.

Hol jelez hibát a Számlázz.hu?#

A Számla Agent műveletenként és válaszverziónként máshogy jelez hibát. A kassza mindet ugyanúgy kezeli:

Fejlécben: a szlahu_error és a szlahu_error_code fejléc URL-kódolt üzenetet és kódot tartalmaz.
Szöveges válaszban: a törzs [ERR] jelöléssel kezdődik, utána jön az üzenet és egy Java stack trace. A kassza csak az üzenetet és a kódot tartja meg.
XML-ben: a <sikeres>false</sikeres> mellett <hibakod> és <hibauzenet> elem van.
HTTP státusszal: az 5xx válaszból network, minden más ismeretlen formátumból unexpected_response kategóriájú hiba lesz.

Kliensoldali validáció#

Sok hibát a kassza már a kérés előtt észrevesz: hiányzó egységár, ismeretlen áfakulcs, kisbetűs nyugta előtag, túl sok vagy túl nagy melléklet. Ilyenkor validation kategóriájú hibát kapsz code nélkül, és kérés sem megy a Számlázz.hu-hoz.

Validációs hibák

Kliensoldali és szerveroldali hibák kategóriával, kóddal és javítási tippel.

Futtatás a sandboxban

hibakezeles-validacio.ts

import { ,  } from 'kassza'

const  = ()

const  = { : 'Vevő Kft.', : '1111', : 'Budapest', : 'Fő utca 1.' }

async function (: string, : () => <unknown>): <void> {
  try {
    await ()
    .(`${}: sikerült`)
  } catch () {
    if (!()) throw 
    .(, {
      : .,
      : .,
      : .,
      : .,
    })
  }
}

await ('Hiányzó egységár', () =>
  ..({ : , : [{ : 'Termék', : 27 }] }),
)

await ('Ismeretlen áfakulcs', () =>
  ..({
    : ,
    : [{ : 'Termék', : 1_000, : 28 }],
  }),
)

await ('Nem regisztrált számlaszám előtag', () =>
  ..({
    : 'XYZ',
    : ,
    : [{ : 'Termék', : 1_000, : 27 }],
  }),
)

await ('Kisbetűs nyugta előtag', () =>
  ..({
    : 'nygt',
    : 'készpénz',
    : [{ : 'Kávé', : 890, : 27 }],
  }),
)

Számla létrehozás · action-xmlagentxmlfile

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamla xmlns="http://www.szamlazz.hu/xmlszamla" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.szamlazz.hu/xmlszamla https://www.szamlazz.hu/szamla/docs/xsds/agent/xmlszamla.xsd">
  <beallitasok>
    <szamlaagentkulcs>••••••••</szamlaagentkulcs>
    <eszamla>false</eszamla>
    <szamlaLetoltes>true</szamlaLetoltes>
    <valaszVerzio>2</valaszVerzio>
    <aggregator>3UMUqqWEJ7bXfJp9KXNWcrddY9sKjDVD</aggregator>
  </beallitasok>
  <fejlec>
    <keltDatum>2026-11-05</keltDatum>
    <teljesitesDatum>2026-11-05</teljesitesDatum>
    <fizetesiHataridoDatum>2026-11-05</fizetesiHataridoDatum>
    <fizmod>Átutalás</fizmod>
    <penznem>HUF</penznem>
    <szamlaNyelve>hu</szamlaNyelve>
    <szamlaszamElotag>XYZ</szamlaszamElotag>
  </fejlec>
  <elado></elado>
  <vevo>
    <nev>Vevő Kft.</nev>
    <irsz>1111</irsz>
    <telepules>Budapest</telepules>
    <cim>Fő utca 1.</cim>
    <sendEmail>false</sendEmail>
  </vevo>
  <tetelek>
    <tetel>
      <megnevezes>Termék</megnevezes>
      <mennyiseg>1</mennyiseg>
      <mennyisegiEgyseg>db</mennyisegiEgyseg>
      <nettoEgysegar>1000</nettoEgysegar>
      <afakulcs>27</afakulcs>
      <nettoErtek>1000</nettoErtek>
      <afaErtek>270</afaErtek>
      <bruttoErtek>1270</bruttoErtek>
    </tetel>
  </tetelek>
</xmlszamla>

Számla létrehozás · válasz, HTTP 200

content-type: application/xml; charset=UTF-8
szlahu_error: A%20megadott%20sz%C3%A1mlasz%C3%A1m%20el%C5%91tag%20nem%20megfelel%C5%91.
szlahu_error_code: 202
set-cookie: JSESSIONID=E77C9FD25D3D8A0AED30550E; Path=/szamla; Secure; HttpOnly

<?xml version="1.0" encoding="UTF-8"?>
<xmlszamlavalasz xmlns="http://www.szamlazz.hu/xmlszamlavalasz">
  <sikeres>false</sikeres>
  <hibakod>202</hibakod>
  <hibauzenet>A megadott számlaszám előtag nem megfelelő.</hibauzenet>
</xmlszamlavalasz>

Konzol

Hiányzó egységár {
  kod: undefined,
  kategoria: 'validation',
  uzenet: '1. tétel (Termék): A tételnél add meg a netUnitPrice vagy a grossUnitPrice mezőt.',
  tipp: undefined
}
Ismeretlen áfakulcs {
  kod: undefined,
  kategoria: 'validation',
  uzenet: '1. tétel (Termék): Ismeretlen áfakulcs: 28',
  tipp: undefined
}
Nem regisztrált számlaszám előtag {
  kod: 202,
  kategoria: 'validation',
  uzenet: '[202] A megadott számlaszám előtag nem megfelelő.',
  tipp: 'Csak a Beállítások / Előtagok menüpontban rögzített és engedélyezett előtag használható.'
}
Kisbetűs nyugta előtag {
  kod: undefined,
  kategoria: 'validation',
  uzenet: 'A nyugta előtag csak nagybetűt és számot tartalmazhat, kapott: nygt (337).',
  tipp: undefined
}

Tesztfiók#

Fejlesztéshez használj Számlázz.hu tesztfiókot. A tesztfiókban 10 percenként legfeljebb 500 számla készíthető, a túllépés 167-es (rate_limit) hibát ad. Automata tesztekhez ezért inkább a mock klienst vagy a hamis Számla Agentet használd, ezek nem hívnak hálózatot.

Hibakategóriák#

error.category	Jelentés	Érdemes újrapróbálni?
`validation`	Hibás adat: a kassza a kérés előtt utasította el, vagy a Számlázz.hu nem fogadta el.	Nem. Javítsd a bemenetet.
`duplicate`	A rendelésszám vagy a hívásazonosító már foglalt, a bizonylat valószínűleg létezik.	Nem. Kérdezd le a meglévőt.
`partial_success`	A bizonylat elkészült, csak egy mellékhatás (az e-mail) hiúsult meg.	Soha. Ne állítsd ki újra.
`not_found`	Nincs ilyen bizonylat.	Nem.
`auth`	Hibás Agent kulcs, vagy böngészős bejelentkezés zavarja az Agentet.	Nem. Javítsd a hitelesítést.
`account`	Előfizetés, e-számla vagy fiókbeállítás miatti hiba, embernek kell beavatkoznia.	Nem.
`maintenance`	A Számlázz.hu karbantart (1-es kód).	Lekérdezésnél a kassza magától újrapróbál.
`network`	Hálózati hiba vagy 5xx válasz. Írásnál a kimenet bizonytalan.	Lekérdezésnél igen. Írásnál előbb keress rendelésszámra.
`timeout`	Nem jött válasz az időkorláton belül. Írásnál a kimenet bizonytalan.	Mint a network.
`rate_limit`	A tesztfiókban rövid idő alatt túl sok bizonylat készült (167-es kód).	Nem automatikusan. Várj néhány percet.
`attempt_limit`	Ezt a kérést már ötször sikertelenül küldték el, ezért a kassza el sem küldi (próbálkozásnapló).	Nem. Javítsd a hibát, majd töröld a számlálót a resetAttempts() hívással.
`configuration`	Hiányzó vagy hibás kliensbeállítás, például nincs Agent kulcs.	Nem. Javítsd a konfigurációt.
`unexpected_response`	A Számlázz.hu ismeretlen formátumban válaszolt.	Nem. Jelentsd a hibát.
`unknown`	Kód nélküli vagy ismeretlen kódú hiba a Számlázz.hu-tól.	Nem.

Két kategória nem a Számlázz.hu-tól jön, hanem a kassza védelmeiből: az in_progress azt jelenti, hogy egy másik folyamat éppen ugyanezt a bizonylatot állítja ki (a createOnce zárja miatt), a store_unavailable pedig azt, hogy egy kötelezőnek beállított tároló (zár vagy fail-closed próbálkozás-napló) nem érhető el. Egyik esetben sem ment ki kérés, és egyik sem újrapróbálható automatikusan.

Hibakódok#

Az alábbi táblázat a kassza által ismert Számlázz.hu hibakódokat mutatja. Az ismeretlen kódú hiba unknown kategóriát kap, de a Számlázz.hu eredeti üzenete ilyenkor is megmarad a message mezőben.

Kód	Kategória	Jelentés	Mit tegyél?
1	`maintenance`	Rendszerkarbantartás, kérem próbálja meg pár perc múlva.	A Számlázz.hu oldalán van karbantartás, néhány perc múlva próbáld újra.
3	`auth`	Sikertelen bejelentkezés.	Ellenőrizd az Agent kulcsot. Csak kisbetűs kulcsot fogad el a rendszer.
7	`not_found`	Hiányzó adat: ismeretlen számlaszám, rendelésszám vagy külső azonosító.	–
8	`account`	Nincs jogosultság vagy megfelelő díjcsomag a művelet elvégzéséhez.	Az Agentes nyugtakibocsátás a #free csomagban nem érhető el, vagy a felhasználó szerepköre nem engedi. Megbízottként a megbízott díjcsomagja számít.
17	`account`	Nem megengedett művelet.	Megbízotti felhasználó például nem ismételhet számlát.
49	`account`	A tanúsítvány használatához jelszó szükséges.	Az e-számla tanúsítványához tartozó jelszót a Számlázz.hu felületén kell beállítani.
52	`validation`	Az áfakulcs nem értelmezhető.	Használd a VatRate típusban felsorolt áfakulcsok egyikét.
53	`validation`	Hiányzó XML fájl.	Az XML-t fájlként kell elküldeni multipart/form-data kérésben.
54	`account`	E-számla készítés nincs engedélyezve.	Az előfizetési csomag nem tartalmazza az e-számlát, vagy nincs tanúsítvány. Próbáld eInvoice: false beállítással.
55	`account`	E-számla aláírása sikertelen.	A tanúsítvány lejárt, vagy az időbélyeg szerver nem érhető el.
56	`partial_success`	A bizonylat elkészült, de az értesítő e-mail kiküldése sikertelen.	NE állítsd ki újra a bizonylatot. Kérdezd le rendelésszám vagy külső azonosító alapján, és küldd ki az e-mailt később.
57	`validation`	XML beolvasási hiba.	A küldött XML nem felel meg az XSD-nek. A részleteket a hibaüzenet tartalmazza.
68	`validation`	Már létezik cég ezzel az adószámmal és számlaszám-előtaggal.	A megbízói fiók csatlakozásához egyeztess másik megbízotti előtagot a megbízóval.
71	`duplicate`	Már létező rendelésszám.	A fiókban be van kapcsolva a rendelésszám ismétlődés tiltása. Ez a bizonylat valószínűleg már elkészült.
101	`validation`	A bejelentkezési név már foglalt.	Új megbízói fiók létrehozásakor másik dedikált felhasználói e-mail címet adj meg.
135	`auth`	Számla Agent futtatásához lépj ki a Számlázz.hu rendszerből a böngészőben.	–
136	`account`	Bejelentkezési hiba, lépj be a Számlázz.hu rendszerébe böngészőn keresztül.	Lejárt előfizetés vagy rendezetlen díj. Ellenőrizd a Szolgáltatáscsomagom menüpontot.
137	`account`	Nincs engedély számlázási fiók létrehozására Számla Agenten keresztül.	Az action-agent_ceg_mb interfész engedélyét a Számlázz.hu ügyfélszolgálatán kell kérni, tesztfiókra is.
152	`duplicate`	Már létező rendelésszám.	A fiókban be van kapcsolva a rendelésszám ismétlődés tiltása. Ez a bizonylat valószínűleg már elkészült.
164	`auth`	A funkciót csak egyetlen fiókhoz hozzáférő felhasználó használhatja.	Használj Agent kulcsot felhasználónév és jelszó helyett. Megbízottként minden megbízóhoz külön dedikált felhasználó kell.
167	`rate_limit`	A tesztfiókban túllépted a rövid idő alatt kiállítható bizonylatok számát.	Tesztfiókban legfeljebb 500 bizonylat készíthető 10 percenként. Várj néhány percet, ne próbáld újra automatikusan.
200	`validation`	Ezt az előtagot ugyanezzel az adószámmal egy másik számlázási fiók használja.	Válassz másik előtagot.
202	`validation`	A megadott számlaszám előtag nem megfelelő.	Csak a Beállítások / Előtagok menüpontban rögzített és engedélyezett előtag használható.
250	`account`	A fiók nem használható, mert a fiókgazda még nem vette birtokba, vagy a meghatalmazás nincs elfogadva.	Megbízotti kapcsolatnál a megbízónak birtokba kell vennie a fiókot. Könyvelői vagy aggregátor meghatalmazást a Számlázz.hu felületén kell elfogadni.
259	`validation`	A tétel nettó értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
260	`validation`	A tétel áfa értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
261	`validation`	A tétel bruttó értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
262	`validation`	A tétel nettó értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
263	`validation`	A tétel áfa értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
264	`validation`	A tétel bruttó értéke nem megfelelő.	Használd a tételeknél a netUnitPrice vagy grossUnitPrice mezőt, és hagyd, hogy a csomag számolja ki az összegeket.
309	`validation`	Érvénytelen adat.	Ellenőrizd a hibaüzenetben megnevezett mezőt, adószámnál előtte a taxpayer.query() hívással.
335	`not_found`	A hivatkozott díjbekérő nem található.	–
336	`validation`	A nyugta előtag már számlákhoz használatban van.	Nyugtához olyan előtag kell, amit számlán még nem használtál.
337	`validation`	A nyugta előtag formátuma hibás.	Az előtag csak nagybetűt és számot tartalmazhat.
338	`duplicate`	A hívásazonosító már létezik.	Ezzel a callId-val már készült nyugta, kérdezd le a meglévőt.
339	`not_found`	A nyugtaszám nem létezik.	–
340	`validation`	A kifizetett összeg eltér a bruttó végösszegtől.	–
352	`validation`	A számla kelte csak a mai nap lehet.	A dátumot magyar idő (Europe/Budapest) szerint kell megadni, nem UTC szerint.
353	`account`	Nincs egyetlen érvényes számlaszám-előtag sem.	A Beállítások / Előtagok oldalon hozz létre vagy engedélyezz egy előtagot.
354	`validation`	Ez a számlaszám-előtag nem használható.	Megbízottként csak a megbízóval egyeztetett, a cégedhez kötött előtagot használhatod.
356	`validation`	A megadott számlaszám-előtag helyett másikat kell használni.	A hibaüzenet megnevezi a használandó előtagot, a suggestedPrefix() kiolvassa.
357	`validation`	Add meg a számlaszám-előtagot.	Megbízotti számlázásnál mindig küldd el az egyeztetett előtagot (prefix).
358	`account`	Ezt a számlát csak a fiók tulajdonosa sztornózhatja.	–
359	`account`	Ez a számla megbízott számlakibocsátás keretében készült, a sztornót a megbízott végezheti.	–
360	`validation`	Az előtag nem módosítható, mert már készült vele bizonylat.	Hozz létre új számlatömböt új előtaggal.
362	`validation`	Ezt az előtagot ez az adószám korábban már használta.	Válassz másik előtagot.
363	`validation`	A tétel bruttó értékének egész számnak kell lennie.	Forintos nyugtán a bruttó egész szám, a nettó és az áfa legfeljebb 2 tizedes, és a nettó + áfa pontosan a bruttó.
364	`validation`	A tétel nettó értéke maximum 2 tizedes jegyet tartalmazhat.	Forintos nyugtán a bruttó egész szám, a nettó és az áfa legfeljebb 2 tizedes, és a nettó + áfa pontosan a bruttó.
365	`validation`	A tétel áfa értéke maximum 2 tizedes jegyet tartalmazhat.	Forintos nyugtán a bruttó egész szám, a nettó és az áfa legfeljebb 2 tizedes, és a nettó + áfa pontosan a bruttó.
395	`validation`	Érvénytelen áfakulcs.	Használd a VatRate típusban felsorolt áfakulcsok egyikét.
396	`validation`	A megadott dátum túl korai.	A kelte és a teljesítés dátuma nem lehet a lezárt időszakban.
489	`account`	Ez a számla megbízott számlakibocsátás keretében készült, az ismétlést a megbízott végezheti.	–
491	`account`	Új kata adónem mellett vállalkozás felé nem állítható ki bizonylat.	A fiókban bekapcsolt KATA-védelem tiltja. Hagyd el a vevő adószámát, vagy kapcsold ki a védelmet a saját felelősségedre.
493	`account`	Ezt a számlát csak a fiók tulajdonosa helyesbítheti.	–
494	`account`	Ez a számla megbízott számlakibocsátás keretében készült, a helyesbítést a megbízott végezheti.	–
506	`validation`	A jelszó túl rövid.	A dedikált felhasználó jelszava legalább 8 karakter legyen.
507	`validation`	A jelszó túl hosszú.	A dedikált felhasználó jelszava legfeljebb 128 karakter lehet.
520	`account`	Nincs elegendő törlőkódod, kérlek tölts fel újat.	Tölts fel új adattörlő kódokat a Számlázz.hu fiókodba. A bizonylat nem jött létre.
521	`validation`	Jelenleg csak a Számlázz.hu ajánlott számlaképpel használható a törlőkód.	Adattörlő kódot csak az alapértelmezett sablonnal kérj: számlánál az ajánlott számlaképpel (SzlaMost), nyugtánál a normál A4-es sablonnal.
524	`account`	A nyugtaszám-előtag nincs engedélyezve.	A Beállítások / Előtagok oldalon engedélyezd az előtag használatát. Meglévő nyugta sztornója ettől még működik.
537	`validation`	Egy tételhez legfeljebb 400 adattörlő kód adható.	–
538	`account`	Adattörlő kód demo- és tesztfiókban nem használható.	–
539	`account`	Nincs bekapcsolva az adattörlő kód használata.	A számlázási beállításokban kapcsold be az adattörlő kódot.
551	`validation`	Egyszerűsített számlakép OSS vagy nem magyar adószám mellett nem használható.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.
552	`validation`	Egyszerűsített számlaképen legfeljebb két tétel adható meg.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.
553	`validation`	Egyszerűsített számlakép esetén érvénytelen adókulcs.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.
554	`validation`	Egyszerűsített számlaképű számla nem helyesbíthető.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.
555	`validation`	Egyszerűsített számlaképen a tételek áfakulcsai nem különbözhetnek.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.
556	`validation`	Egyszerűsített számlakép szállítólevélen és helyesbítő számlán nem használható.	Az egyszerűsített számlakép (simpleItems) szabályait lásd a docs utazásszervezőknek szóló oldalán.

Minden kódnak saját oldala is van a hibakódok között, magyarázattal és kassza-példával.

Következő lépések#

Munkamenet (session cookie)

Hogyan tartja életben a kassza a munkamenetet, és mit tegyél serverless környezetben.

Pontosan egyszer

createOnce, kitiltás elleni védelem folyamatok között, karbantartási szünet.

Tesztelés

Hibák szimulálása mock klienssel, hálózat nélkül.

Hamis Számla Agent

Elveszett válasz, karbantartás és részleges siker a valódi kassza kódon.